103 lines
2.1 KiB
Markdown
103 lines
2.1 KiB
Markdown
|
# 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.
|