151 lines
4.0 KiB
Markdown
151 lines
4.0 KiB
Markdown
# Arkie Library Backend
|
|
|
|
Go backend for the ARK Library / ARK Database website.
|
|
|
|
If Go is new for you: start with **[docs/GO_FOR_BEGINNERS.md](docs/GO_FOR_BEGINNERS.md)**, then read **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
|
|
|
|
For local Docker/OrbStack development, see **[docs/LOCAL_ORBSTACK.md](docs/LOCAL_ORBSTACK.md)**.
|
|
|
|
## What this service does
|
|
|
|
- Serves public library data under `/api`.
|
|
- Serves uploaded files under `/uploads`.
|
|
- Provides admin login and admin CRUD APIs for resources.
|
|
- Supports wallet sign-in with Ethereum personal-sign messages.
|
|
- Stores data in PostgreSQL.
|
|
- Stores uploads locally by default, or in S3 when configured.
|
|
|
|
## Tech stack
|
|
|
|
- Go module: `github.com/arkie/ark-database`
|
|
- HTTP router: `github.com/go-chi/chi/v5`
|
|
- Database: PostgreSQL via `github.com/jackc/pgx/v5/pgxpool`
|
|
- Auth: JWT via `github.com/golang-jwt/jwt/v5`
|
|
- Password hashing: bcrypt
|
|
- Wallet signature verification: `github.com/ethereum/go-ethereum`
|
|
- Optional uploads: AWS S3 SDK v2
|
|
|
|
## Folder map
|
|
|
|
```text
|
|
cmd/server/main.go # application entry point: config, DB, router, endpoints
|
|
internal/config/config.go # environment variables and default values
|
|
internal/db/db.go # PostgreSQL connection pool
|
|
internal/auth/ # JWT signing/parsing for admin and wallet users
|
|
internal/handlers/ # HTTP handlers: public, admin, upload, wallet auth
|
|
internal/seed/seed.go # optional initial admin user
|
|
migrations/ # SQL schema files, apply manually
|
|
static/ # bundled static assets copied into uploads
|
|
```
|
|
|
|
## Quick local run
|
|
|
|
### Option A: OrbStack / Docker Compose
|
|
|
|
```bash
|
|
cd Arkie-Library-Backend
|
|
docker compose up --build
|
|
```
|
|
|
|
Then check:
|
|
|
|
```bash
|
|
curl http://localhost:8080/healthz
|
|
```
|
|
|
|
See **[docs/LOCAL_ORBSTACK.md](docs/LOCAL_ORBSTACK.md)** for details.
|
|
|
|
### Option B: Manual PostgreSQL + Go
|
|
|
|
#### 1) Start PostgreSQL
|
|
|
|
Example with Docker:
|
|
|
|
```bash
|
|
docker run --name ark-postgres \
|
|
-e POSTGRES_USER=ark \
|
|
-e POSTGRES_PASSWORD=ark \
|
|
-e POSTGRES_DB=arkdb \
|
|
-p 5432:5432 \
|
|
-d postgres:16
|
|
```
|
|
|
|
#### 2) Apply schema once
|
|
|
|
`migrations/001_init.sql` is for a fresh empty database. Do not run it twice on the same DB unless you reset the DB first.
|
|
|
|
```bash
|
|
cd Arkie-Library-Backend
|
|
export DATABASE_URL='postgres://ark:ark@localhost:5432/arkdb?sslmode=disable'
|
|
psql "$DATABASE_URL" -f migrations/001_init.sql
|
|
```
|
|
|
|
Wallet nonce schema is normally auto-created at app startup because `RUN_WALLET_AUTH_SCHEMA` defaults to true. If you want to apply it manually and disable startup DDL:
|
|
|
|
```bash
|
|
psql "$DATABASE_URL" -f migrations/002_wallet_auth.sql
|
|
export RUN_WALLET_AUTH_SCHEMA=false
|
|
```
|
|
|
|
#### 3) Configure env
|
|
|
|
Copy the example and edit values as needed:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
This project does not auto-load `.env`; either export variables in your shell or run with a dotenv helper.
|
|
|
|
#### 4) Run the server
|
|
|
|
```bash
|
|
go run ./cmd/server
|
|
```
|
|
|
|
Check health:
|
|
|
|
```bash
|
|
curl http://localhost:8080/healthz
|
|
```
|
|
|
|
## Useful commands
|
|
|
|
```bash
|
|
# Format all Go files
|
|
gofmt -w .
|
|
|
|
# Compile and run all package tests
|
|
go test ./...
|
|
|
|
# Run the backend
|
|
go run ./cmd/server
|
|
|
|
# Build a local binary
|
|
go build -o ./bin/server ./cmd/server
|
|
```
|
|
|
|
## Environment variables
|
|
|
|
See `.env.example` for all variables. Important ones:
|
|
|
|
| Variable | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `HTTP_ADDR` | `:8080` | Listen address |
|
|
| `DATABASE_URL` | `postgres://ark:ark@localhost:5432/arkdb?sslmode=disable` | PostgreSQL connection |
|
|
| `JWT_SECRET` | `dev-insecure-change-me` | JWT signing key; change in production |
|
|
| `UPLOAD_DIR` | `./uploads` | Local upload directory |
|
|
| `CORS_ORIGINS` | empty | Comma-separated allowed browser origins |
|
|
| `SEED_ADMIN` | false | Set `true`/`1` to create first admin if none exists |
|
|
| `ADMIN_EMAIL` | `admin@ark.local` | Seed admin email |
|
|
| `ADMIN_PASSWORD` | `admin123` | Seed admin password |
|
|
| `S3_BUCKET` | empty | Enables S3 uploads when set |
|
|
|
|
## API docs
|
|
|
|
See **[docs/API.md](docs/API.md)**.
|
|
|
|
## Agent notes
|
|
|
|
AI/coding agent instructions are in **[AGENTS.md](AGENTS.md)**.
|