Development

Repository layout

The module name is postgis-service, targets Go 1.22, and replaces module shared with sibling ../shared.

main.go                 HTTP setup and routes
internal/api/           handlers and auth middleware
internal/store/         metadata persistence
internal/db/            metadata connection and migration
internal/cluster/       database lifecycle SQL
internal/access/        roles, grants, HBA
internal/settings/      curated PostgreSQL settings
internal/jobs/          persistent worker
internal/backup/        pg_dump/pg_restore
internal/ingest/        GDAL imports
internal/terminal/      WebSocket terminals
web/                    templates and assets
deploy/                 systemd, Apache, environment examples
docs/                   this documentation

Dependencies

Direct Go dependencies are Gorilla Mux 1.8.1, lib/pq 1.10.9, and the sibling shared module. The module graph also lists creack/pty, Gorilla WebSocket, x/sys, and x/term as indirect dependencies.

Runtime external commands are feature-dependent:

Feature	Commands/services
Core	Metadata PostgreSQL, Central auth PostgreSQL, managed PostgreSQL
Backup/restore	pg_dump, pg_restore
Import	ogr2ogr, ogrinfo
psql terminal	psql, PTY support
Server terminal	systemctl, journalctl, df, free, ps, vacuumdb, reindexdb, pg_dump, pg_restore
Log terminal	journalctl -u postgresql

No command-version checks or startup dependency probes exist; missing commands fail only when their features run.

Local setup

export POSTGIS_DATABASE_URL='postgres://postgres:password@127.0.0.1:5432/acugis_meta?sslmode=disable'
export POSTGIS_AUTH_DATABASE_URL="$POSTGIS_DATABASE_URL"
export POSTGIS_SECRETS_KEY='01234567890123456789012345678901'
export POSTGIS_SKIP_AUTH=1
go run .

POSTGIS_SKIP_AUTH is suitable only for isolated local development. The metadata migration creates service tables, but Central auth tables must already exist even when bypass is enabled because main still opens the auth store before middleware execution.

Tests and quality checks

go test ./...
go vet ./...
gofmt -w <changed-go-files>

Current tests cover portions of backup paths, HBA rendering, settings validation, terminal origins, and terminal SQL/restriction behavior. Source contains no documented integration-test harness, fixture database, lint configuration, coverage threshold, or CI definition for this service.

For documentation:

python -c "import yaml; yaml.safe_load(open('docs/openapi.yaml', encoding='utf-8'))"

PyYAML availability is not declared by the project. Use any YAML 1.2-capable parser if unavailable, and use an OpenAPI 3.1 validator for semantic validation when available.

Change discipline

• Do not add routes without updating API and openapi.yaml.
• Keep migration statements idempotent; there is no migration version framework.
• Preserve identifier validation before constructing PostgreSQL SQL.
• Treat subprocess arguments, filesystem roots, forwarded headers, and terminal commands as security boundaries.
• Add tests around job partial failures and persistence changes; the worker has no transaction spanning remote PostgreSQL and metadata.