Skip to content

Development

Development environment

Prerequisites:

  • Federation checkout with geovault/ and shared/
  • Go 1.25+
  • PostgreSQL with Central auth schema (required) and preferably metadata DB
  • GDAL/OGR tools on PATH for GIS features
  • A working directory where web/ and data/ resolve, normally the geovault root
cd geovault
export GEOVAULT_AUTH_DATABASE_URL='postgres://...@127.0.0.1:5432/central?sslmode=disable'
export DATABASE_URL='postgres://...@127.0.0.1:5432/acugis_meta?sslmode=disable'
go run .

UI: open http://127.0.0.1:8085/ (redirects to /drive) after obtaining a Central session cookie for the same host strategy you use locally (hosts file / proxy).

On PowerShell, use $env:GEOVAULT_AUTH_DATABASE_URL = '...' and $env:DATABASE_URL = '...'. The server address is fixed at :8085; source does not expose a port environment variable.

Project layout

See Architecture. Tests live beside packages as *_test.go.

Coding standards (observed)

  • Handlers in internal/api own HTTP concerns; persistence in internal/db; catalog in internal/store
  • Prefer parameterized SQL; quote identifiers via internal/pgutil helpers for dynamic table/column names
  • Dataset mutations should call requireDatasetPermission / RequireDatasetView as appropriate
  • Register new dataset resources with registerDatasetResource so Central ACLs exist
  • Keep folder scope in version lookups and filesystem paths; same-name datasets can exist in different folders
  • Treat store.Versions mutation as a critical consistency area: it is global, unsynchronized, and persisted as a complete snapshot
  • Avoid inventing env vars without documenting them and wiring os.Getenv
  • Do not add exploit-oriented samples; keep credentials out of commits

Run gofmt on Go changes. No repository-local golangci-lint configuration, generated-code workflow, API generator, or enforced style document was found; additional standards are unknown.

Running tests

cd geovault
go test ./...

The reviewed tree has nine test files: one template parser test, one dataset-scope test, and seven editor tests covering sanitization, preview IDs, OGR/Shapefile behavior, and PostGIS preview helpers. Most HTTP handlers, migrations, auth integration, background jobs, external clients, and full workflows have no direct tests.

No GeoVault-specific test runner, coverage threshold, fixture framework, or integration-test environment is defined. go test -race ./... is a useful additional check on supported platforms, especially around the global catalog, but it is a recommendation rather than an existing release gate.

Debugging

Technique Detail
Stdout/stderr logs Standard library log; under systemd → journal (SYSLOG_IDENTIFIER=geovault)
Shapefile edit traces Unconditional log message prefixes named GEOVAULT_DEBUG_SHP_*; these are not environment switches
Vector edit row debug Unconditional GEOVAULT_DEBUG_EDIT_ROWS message prefix; not an environment switch
Job logs geoserver_jobs.log_text / error_message
Local curl Include session cookie; see Examples

There are no request IDs, structured log levels, redaction framework, metrics, health route, or pprof routes registered in main.go. Some logs include paths, table names, row update values, and upstream response bodies; use production logs as potentially sensitive data.

Logging

  • Process logs: Go log to stdout/stderr
  • systemd: journalctl -u geovault -f
  • No dedicated log file path is configured in the unit (journal only)

Adding new endpoints

  1. Implement handler in internal/api.
  2. Register in registerRoutes inside main.go with explicit methods.
  3. Confirm service ACL implications: non-GET/HEAD defaults to edit; connection/database-service paths require admin.
  4. Add dataset ACL checks when the route is dataset-scoped.
  5. Decide whether the route must honor BASE_PATH, folder scope, and caller credential forwarding.
  6. Document the route in docs/api.md and docs/openapi.yaml.
  7. Add focused handler tests for method, auth, invalid input, storage failure, and success.
  8. If a sibling CLI mapping is added, update docs/cli.md.

Adding new database tables

  1. Extend migrateSQL in internal/db/migrate.go with idempotent CREATE/ALTER.
  2. Plan upgrades from every schema shape still expected in deployment; there is no numbered migration history or rollback engine.
  3. Add explicit indexes, FKs, delete behavior, defaults, and checks—do not rely on application convention where integrity matters.
  4. Add typed helpers in internal/db and tests against PostgreSQL where practical.
  5. Ensure external FK targets (especially dashboard_users) exist in the same metadata database.
  6. Decide behavior when db.Meta == nil; only versions currently has JSON fallback.
  7. Document ownership, every column, index, and relation in docs/database.md.
  8. Provide an operator runbook for destructive or long-running changes.

Frontend changes

  • Edit web/*.html, web/app.js, web/style.css
  • Cache-bust query strings (e.g. app.js?v=...) are manual
  • No bundler; restart is enough for Go template re-parse only if templates are re-read (current code parses at startup—restart required for template changes)

Release process

No authoritative GeoVault release process is defined in the reviewed repository. No application version constant, version injection, GeoVault release workflow, packaging script, or verifiable historical application version sequence was found. The parent repository's systemd unit is deployment evidence, not a release pipeline.

A proposed manual baseline (not an existing guarantee):

  1. go test ./...
  2. Back up the metadata/auth databases, version catalog, and /data/projects
  3. Build go build -trimpath -o geovault .
  4. Install the binary plus web/ under the systemd working directory
  5. Restart the service and inspect journal startup/migration output
  6. Smoke-test /api/discovery, catalog/version reads, one authenticated download, and configured integrations
  7. Verify queued/running jobs manually because restart recovery is absent

Record user-visible changes in Changelog. The 1.0.0 entry is a documentation baseline dated 2026-07-15, not evidence of an earlier published artifact.