Andriy Oblivantsev
e00280b653
CI / test (push) Successful in 3s
Integrate asset metadata/storage support, TypeScript client asset APIs, docs updates, and the Leaflet demo while resolving conflicts with recent challenge IP/login persistence changes on main. Made-with: Cursor
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# Momswap Geo Backend
|
|
|
|
Go backend service for user-owned GeoJSON feature collections with Ed25519 authentication and invitation-based onboarding.
|
|
|
|
## What is implemented
|
|
|
|
- Ed25519 challenge-response auth (`/v1/auth/challenge`, `/v1/auth/login`)
|
|
- Hybrid invitation onboarding (signed invite payload + inviter lineage)
|
|
- User registration with ownership proof (`/v1/auth/register`)
|
|
- Per-user collections and Point feature CRUD endpoints
|
|
- Static no-build frontend (`web/`) using Vue + Vuetify from CDN
|
|
- Reusable TypeScript API client (`libs/geo-api-client`) using `@noble/ed25519`
|
|
- Bun tests for the TS client and Go tests for API flows
|
|
- Gitea CI workflow running Go and Bun test suites
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
go test ./...
|
|
go run ./cmd/api
|
|
```
|
|
|
|
Run tests via Docker (avoids local permission issues, e.g. `var/`):
|
|
|
|
```bash
|
|
docker compose --profile test run --rm test
|
|
```
|
|
|
|
Primary deployed base URL: `https://momswap.produktor.duckdns.org/`.
|
|
|
|
Local default (for development): `http://localhost:8122`.
|
|
|
|
Optional environment variables:
|
|
|
|
- `ADDR` (default `:8122`)
|
|
- `ADMIN_PUBLIC_KEY` — **required for registration**: bootstrap admin + service key for `register-by-signature`. Generate with `./bin/gen-admin-key.sh`
|
|
- `SERVICE_PUBLIC_KEY` (public key users sign to register; defaults to `ADMIN_PUBLIC_KEY`)
|
|
|
|
**Deployment:** Set `ADMIN_PUBLIC_KEY` before starting. Without it, `/v1/service-key` returns 503 and registration is disabled.
|
|
|
|
## Docker Compose
|
|
|
|
Generate server keys (creates `etc/server-service.*`), then build and run:
|
|
|
|
```bash
|
|
./bin/gen-server-keys.sh
|
|
COMPOSE_BAKE=true docker compose up --build -d
|
|
```
|
|
|
|
Or use `./bin/up.sh` which runs the key generation if needed.
|
|
|
|
This starts:
|
|
|
|
- `db` (`postgis/postgis`) on `5432` inside the container, exposed as **`7721`** on the host for remote access
|
|
- `api` on `8122` — uses PostgreSQL via `DATABASE_URL` (migrations run on startup)
|
|
- `minio` (S3-compatible storage) with admin UI on `8774` and internal S3 API on `9000`
|
|
|
|
**Remote DB access** (e.g. `postgres://momswap:momswap@HOST_IP:7721/momswap?sslmode=disable`): The init script `etc/pg-init-remote.sh` configures `pg_hba.conf` for remote connections on fresh installs. If the DB was initialized before that was added, run once: `./bin/fix-pg-remote.sh`
|
|
|
|
Stop the service:
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
For local development with auto-rebuild on file changes:
|
|
|
|
```bash
|
|
COMPOSE_BAKE=true docker compose --profile dev up --watch
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `api` service listens on `8122` inside the container, mapped to host `8122` (reverse proxy at `https://momswap.produktor.duckdns.org`).
|
|
- `api` service uses the production `runtime` image target.
|
|
- `api-dev` profile uses the `dev` image target and Docker Compose watch.
|
|
- DB defaults can be overridden via `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`.
|
|
- S3 defaults can be overridden via `S3_ENDPOINT`, `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_USE_PATH_STYLE`, `S3_USE_TLS`.
|
|
|
|
## Frontend
|
|
|
|
Frontend is served by the Go backend at runtime.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
go run ./cmd/api
|
|
```
|
|
|
|
Then visit:
|
|
|
|
- Production: `https://momswap.produktor.duckdns.org/web/`
|
|
- Local: `http://localhost:8122/web/`
|
|
- Local Leaflet demo: `http://localhost:8122/web/leaflet-demo.html`
|
|
|
|
## Documentation
|
|
|
|
| Doc | Description |
|
|
|-----|-------------|
|
|
| [docs/frontend-development.md](docs/frontend-development.md) | Demo app (`web/`), client build, local dev |
|
|
| [docs/typescript-frontend-integration.md](docs/typescript-frontend-integration.md) | TypeScript client API, integration flow, examples |
|
|
| [docs/ed25519-security-use-cases.md](docs/ed25519-security-use-cases.md) | Ed25519 auth flows, registration, signatures |
|
|
| [docs/geo-auth-backend-plan.md](docs/geo-auth-backend-plan.md) | Architecture and planning |
|
|
| [docs/assets-storage-and-sharing.md](docs/assets-storage-and-sharing.md) | Asset metadata, dedup, visibility rules, and `properties.assets` contract |
|
|
| [docs/docker-minio-local-dev.md](docs/docker-minio-local-dev.md) | MinIO compose topology, bucket bootstrap, and local verification |
|
|
|
|
## API client library
|
|
|
|
Path: `libs/geo-api-client`
|
|
|
|
```bash
|
|
cd libs/geo-api-client
|
|
bun install
|
|
bun test
|
|
bun run build
|
|
```
|
|
|
|
## CI
|
|
|
|
Workflow: `.gitea/workflows/ci.yml`
|
|
|
|
- `go test ./...`
|
|
- `bun test` in `libs/geo-api-client`
|
|
|
|
## Testing policy
|
|
|
|
- Keep fast unit tests as the default (`go test ./...`).
|
|
- If a test requires a real Postgres instance, use embedded/ephemeral Postgres in the test process or test fixture lifecycle.
|
|
- Do not require manually running an external Postgres container for routine test runs.
|