# 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`:

```bash
docker compose up --build
```

Then test:

```bash
curl http://localhost:8080/healthz
```

Expected output:

```text
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:

```text
email: admin@ark.local
password: admin123
```

Override if needed:

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

## Frontend connecting to local backend

In `Arkie-Library-Frontend`, use:

```bash
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:

```bash
docker compose up db
```

In another terminal:

```bash
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:

```bash
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.