Getting Started

This guide covers setting up and running the Acctz Ledger project for local development.

---

Prerequisites

↑ Back to top

• Java 17+ (recommend Azul Zulu for ARM Macs)
• Docker & Docker Compose
• Node.js 18+ (for documentation site)
• Gradle (wrapper included, no install needed)
• Git with SSH access to GitLab

---

GitLab SSH Setup

↑ Back to top

To clone and push to GitLab, you need an SSH key configured.

1. Check for Existing Keys

ls -la ~/.ssh

Look for files like id_ed25519 and id_ed25519.pub (or id_rsa/id_rsa.pub).

2. Generate a New SSH Key

If no key exists, create one:

ssh-keygen -t ed25519 -C "your.email@example.com"

When prompted:

• Press Enter to accept the default file location (~/.ssh/id_ed25519)
• Enter a passphrase (recommended) or press Enter for none

3. Start the SSH Agent

eval "$(ssh-agent -s)"

4. Add Your Key to the Agent

ssh-add ~/.ssh/id_ed25519

On macOS, to persist across restarts, add to ~/.ssh/config:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

5. Copy the Public Key

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
cat ~/.ssh/id_ed25519.pub
# Then manually copy the output

6. Add Key to GitLab

1. Log in to GitLab
2. Go to Settings > SSH Keys (or navigate to /-/profile/keys)
3. Paste your public key in the Key field
4. Give it a descriptive Title (e.g., "MacBook Pro - 2026")
5. Optionally set an Expiration date
6. Click Add key

7. Test the Connection

ssh -T git@gitlab.com

For self-hosted GitLab:

ssh -T git@your-gitlab-domain.com

You should see a welcome message like:

Welcome to GitLab, @username!

Troubleshooting

Permission denied (publickey):

• Verify the key is added to the agent: ssh-add -l
• Ensure the public key is added to GitLab
• Check you're using the correct GitLab hostname

Multiple GitLab accounts: Add to ~/.ssh/config:

Host gitlab-work
  HostName gitlab.company.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Host gitlab-personal
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

Then clone using the host alias:

git clone git@gitlab-work:group/project.git

---

Project Setup

↑ Back to top

1. Clone the Repository

git clone <repository-url>
cd acctz

2. Configure Shell Environment

Add to your shell profile (~/.zshrc or ~/.bashrc) for persistent access:

# Set base directory (adjust path to your clone location)
export ACCTZ_BASE="/path/to/acctz"

# Source management scripts
source $ACCTZ_BASE/opt/docs-manager.sh
source $ACCTZ_BASE/opt/ledger-docs.sh

Example with iCloud path:

export CLOUD_BASE="$HOME/Library/Mobile Documents/com~apple~CloudDocs/IT"
export ACCTZ_BASE="$CLOUD_BASE/Acctz/acctz"

source $ACCTZ_BASE/opt/docs-manager.sh
source $ACCTZ_BASE/opt/ledger-docs.sh

Reload your shell:

source ~/.zshrc

Verify setup:

acctz help
ledger_docs help

3. Start Infrastructure

acctz start-infra

This starts PostgreSQL and pgAdmin via Docker Compose.

---

Using acctz-manager

↑ Back to top

The acctz command provides a unified interface for managing the project.

Available Commands

Command	Description
acctz help	Show all available commands
acctz status	Show status of all services
acctz start-infra	Start PostgreSQL and pgAdmin
acctz stop-infra	Stop infrastructure containers
acctz build	Build the application (optionally with tests)
acctz start-app	Start the application in Docker
acctz stop-app	Stop the application container
acctz logs	Tail application logs
acctz restart	Restart the application
acctz clean	Clean build artifacts and Docker resources

Common Workflows

Start everything:

acctz start-infra
acctz build
acctz start-app

Rebuild and restart:

acctz build true   # Build with tests
acctz restart

View logs:

acctz logs

---

Local Java Development

↑ Back to top

For IDE-based development without Docker:

1. Start Only Database

acctz start-infra

2. Run from IDE or Command Line

Using Gradle:

./gradlew :ledger:bootRun

Using IDE:

• Open the project in IntelliJ IDEA
• Run LedgerApplication.java with the local profile

3. Configure Local Profile

Set the Spring profile to local for development-friendly settings:

# Environment variable
export SPRING_PROFILES_ACTIVE=local

# Or JVM argument
-Dspring.profiles.active=local

---

Debugging

↑ Back to top

Remote Debug (Docker)

When running in Docker, the application exposes a debug port.

1. Start the app with debugging enabled (default):

acctz start-app

2. Attach your IDE debugger to localhost:5005

IntelliJ Configuration:

• Run > Edit Configurations > Add > Remote JVM Debug
• Host: localhost
• Port: 5005

Local Debug (IDE)

For direct debugging without Docker:

1. Ensure PostgreSQL is running:

acctz start-infra

2. Run LedgerApplication in debug mode from your IDE

3. Set breakpoints and debug normally

Debug Environment Variables

The Docker setup uses these environment variables:

Variable	Default	Description
DEBUG	true	Enable remote debugging
DEBUG_PORT	5005	Debug port
DEBUG_SUSPEND	n	Wait for debugger before starting

---

Access Points

↑ Back to top

Service	URL	Credentials
Ledger API	http://localhost:8080	-
Health Check	http://localhost:8080/actuator/health	-
Documentation	http://localhost:3003	-
pgAdmin	http://localhost:5050	admin@admin.com / admin
PostgreSQL	localhost:5432	postgres / postgres