Arkie-Library-Backend/docs/LOCAL_ORBSTACK.md

Local Development with OrbStack

Yes — this backend can run locally in OrbStack.

This repo includes compose.yaml with:

• db: PostgreSQL 16
• api: the Go backend built from the local Dockerfile

Quick start

From Arkie-Library-Backend:

docker compose up --build

Then test:

curl http://localhost:8080/healthz

Expected output:

ok

Local URLs

Service	URL
Backend API	http://localhost:8080
Health check	http://localhost:8080/healthz
PostgreSQL from Mac host	localhost:5433
PostgreSQL from API container	db:5432

The DB host port is 5433 to avoid conflicts with any local PostgreSQL already using 5432.

Default local admin

When the DB is empty, compose seeds an admin because SEED_ADMIN=true by default:

email: admin@ark.local
password: admin123

Override if needed:

ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='your-password' docker compose up --build

Frontend connecting to local backend

In Arkie-Library-Frontend, use:

VITE_API_URL=http://localhost:8080

Then run your frontend dev server normally.

Running Go locally but DB in OrbStack

For faster backend development, you can run only PostgreSQL in OrbStack and run Go directly on your Mac.

Start DB only:

docker compose up db

In another terminal:

export DATABASE_URL='postgres://ark:ark@localhost:5433/arkdb?sslmode=disable'
export HTTP_ADDR=':8080'
export JWT_SECRET='local-dev-change-me'
export CORS_ORIGINS='http://localhost:5173,http://localhost:3000'
export SEED_ADMIN=true

go run ./cmd/server

Reset local database

This deletes local development data and reruns migrations on next start:

docker compose down -v
docker compose up --build

Important notes

• This is local-only and does not touch the production server.
• migrations/001_init.sql runs only when the PostgreSQL volume is first created.
• If you change migrations and want them reapplied, reset with docker compose down -v.
• Do not use production DATABASE_URL for local development unless you intentionally want to modify production data.