Getting Started

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

---

Prerequisites

↑ Back to top

• Docker & Docker Compose
• Node.js 18+
• 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@git.acctz.dev

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 git.acctz.dev
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Then clone using the host alias:

git clone git@gitlab-work:acctz/workspace.git

---

Project Setup

↑ Back to top

1. Clone the Workspace

git clone git@git.acctz.dev:acctz/workspace.git
cd workspace

2. Clone All Repos

./scripts/acctz.sh clone

This reads repos.conf and clones all required repositories into the correct folder structure.

3. Source acctz.sh (Optional but Recommended)

Add to your ~/.bashrc or ~/.zshrc for persistent access:

source /path/to/repos/workspace/scripts/acctz.sh

Reload your shell:

source ~/.bashrc

Verify:

acctz help

See the workspace scripts guide for --silent and --alias-az options.

4. Build All Projects

acctz build

This installs and builds all projects in dependency order: core → node → node/functions → ui.

---

Starting the Local Environment

↑ Back to top

Start the Database

acctz start      # starts PostgreSQL and pgAdmin via Docker
acctz create-db  # runs Flyway migrations and seeds from Firestore

Start the Node.js API and Sync Service

cd node
npm start

Use --enable-rest or --enable-sync flags to start only the REST API or only the Firestore sync listener:

npm start -- --enable-rest    # REST API only
npm start -- --enable-sync    # Firestore sync only

---

Access Points

↑ Back to top

Service	URL	Credentials
Node.js REST API	http://localhost:3000	Firebase Bearer token required
pgAdmin	http://localhost:5050	admin@admin.com / admin
PostgreSQL	localhost:5432	postgres / postgres

---

Common Commands

↑ Back to top

Command	Description
acctz start	Start PostgreSQL and pgAdmin
acctz stop	Stop all services
acctz status	Show service status
acctz create-db	Run Flyway migrations and seed from Firestore
acctz build	Build all projects
acctz clean	Remove build artifacts
acctz logs [service]	Tail logs for postgres or pgadmin
acctz shell	Open a psql shell into PostgreSQL
acctz open pgadmin	Open pgAdmin in the browser

See the workspace scripts guide for the full command reference.

---

Further Reading

↑ Back to top

• Schema Design - PostgreSQL schema, multi-tenancy, UUIDv7, Firebase integration
• Architecture Plan - Backend architecture and design principles
• Book of Record - Double-entry accounting concepts
• Feature Breakdown - Comprehensive feature list