Skip to content

Installation

Requirements

  • Go 1.25 or newer, as declared by go.mod.
  • A federation checkout containing sibling geovault/ and shared/; go.mod uses replace shared => ../shared.
  • PostgreSQL containing Central's auth tables. Startup requires a reachable auth DSN from GEOVAULT_AUTH_DATABASE_URL, CENTRAL_DATABASE_URL, or DATABASE_URL.
  • The web/ directory and the shared federation UI assets at runtime.
  • Write access to /data/projects, process-relative data/metadata, and the selected version-catalog path.

Install these GDAL/OGR executables on the service PATH: ogrinfo, ogr2ogr, gdalinfo, gdal_translate, and gdalwarp. They support metadata inspection, previews, vector operations, raster clipping, and optional PostGIS import.

Feature-dependent external services are QGIS Publish Service, TileServer registration, PostGIS Service, operator-configured PostgreSQL/PostGIS and GeoServer instances, HTTP(S) import sources, S3-compatible storage, and ArcGIS services. The browser also fetches assets from cdnjs.cloudflare.com, unpkg.com, Google Fonts (fonts.googleapis.com/fonts.gstatic.com), and CARTO basemap hosts. Permit those origins or vendor and modify the assets yourself.

There is no Node/npm build. Go dependencies include Gorilla Mux, lib/pq, AWS SDK for Go, SQLite, go-shp, and the sibling shared module.

Build from source

From the federation checkout:

cd geovault
go mod download
go test ./...
go build -trimpath -o geovault .

PowerShell uses the same commands with go build -trimpath -o geovault.exe ..

No Dockerfile or Compose file is provided or verified. Any container image, Compose definition, GDAL package set, build context, volume layout, environment injection, and reverse proxy are operator-supplied and are not a supported repository installation path.

Manual runtime layout

The parent-repository systemd asset expects:

Path Purpose
/opt/geovault/geovault Binary
/opt/geovault/web/ Templates and static files
/opt/geovault/shared/ui/ Federation shell assets, unless FEDERATION_SHARED_UI_ROOT points elsewhere
/etc/geovault.env Optional systemd environment file
/data/projects/ Hard-coded dataset storage root and default QGIS cleanup root

Copy web/ and ../shared/ui/ with the binary. Create /etc/geovault.env from reviewed placeholders rather than blindly deploying deploy/geovault.env: that tracked draft contains credential-like sample data. Never reuse it; rotate the affected credential if it has ever been accepted by a database. Do not publish environment-file contents.

For a local run:

export GEOVAULT_AUTH_DATABASE_URL='postgres://central:[REDACTED]@127.0.0.1:5432/central?sslmode=disable'
export DATABASE_URL='postgres://meta:[REDACTED]@127.0.0.1:5432/acugis_meta?sslmode=disable'
go run .

DATABASE_URL is optional only for metadata: without it, versions use JSON, but a separate Central auth DSN remains mandatory. The server binds plain HTTP on :8085 (all interfaces), and GEOVAULT_LISTEN does not change that.

Startup sequence

GeoVault opens and migrates the optional metadata database, opens and pings the required Central auth database, loads versions from PostgreSQL or JSON, reconciles GeoServer/catalog and dataset resources, removes legacy timestamped QGIS project directories, parses templates, installs authentication/authorization middleware, then listens on :8085. A badly configured database or missing template is fatal; catalog-load and several reconciliation failures are logged and startup continues.

Production installation

  1. Install the binary, web/, and shared UI assets under /opt/geovault.
  2. Install GDAL/OGR and confirm all five executables are visible to www-data.
  3. Create writable storage and a secret environment file; see Configuration.
  4. Install the parent asset ../systemd/geovault.service, reload systemd, and enable the unit.
  5. Use the parent Apache mapping for /geovault, which strips the prefix and supplies X-Forwarded-Prefix and X-Forwarded-Proto.
  6. Verify Central login, the acugis_session cookie, database access, storage writes, and each enabled external integration.

See Deployment and Troubleshooting. Docker/Compose, Nginx, native TLS, horizontal scaling, and dedicated health endpoints are not provided or verified.