Configuration

GeoVault reads the process environment only; it does not parse .env, YAML, or TOML. The parent systemd unit optionally reads /etc/geovault.env through EnvironmentFile=-/etc/geovault.env.

Do not deploy credentials from deploy/geovault.env. It contains credential-like sample data: replace it with placeholders and rotate the credential if that value has ever been used. Examples below intentionally omit secrets.

Effective environment variables

Variable	Exact default and precedence	Effect
BASE_PATH	Empty. / also normalizes to empty; a leading slash is added and trailing slashes removed.	Mounts application routes at the resulting prefix. For generated URLs, a non-empty X-Forwarded-Prefix header takes precedence per request. With the checked-in Apache prefix-stripping mapping, leave BASE_PATH empty.
GEOVAULT_AUTH_DATABASE_URL	First non-empty auth DSN, before CENTRAL_DATABASE_URL, then DATABASE_URL. No overall default.	Required Central auth database.
CENTRAL_DATABASE_URL	Second auth choice.	Required only when neither higher/lower alternative supplies auth.
DATABASE_URL	Third auth choice; independently, empty disables metadata PostgreSQL.	Metadata database and migrations. If selected for auth, it must also contain Central auth tables.
ACUGIS_SESSION_COOKIE_DOMAIN	Trimmed value; empty means a host-only cookie.	Used by sibling shared/auth when constructing or expiring acugis_session. Set only when Central and services intentionally share cookies across subdomains, and keep the value consistent with Central. GeoVault validates Central-owned sessions; it does not provide login.
FEDERATION_SHARED_UI_ROOT	If non-empty, cleaned and used directly. Otherwise search shared/ui, ../shared/ui, ../../shared/ui from CWD, then shared/ui and ../shared/ui relative to the executable directory; final fallback is CWD-relative shared/ui.	Filesystem root served at /shared/ui/.
GEOVAULT_VERSIONS_JSON	Trimmed non-empty value wins over GEOVAULT_DATA_DIR.	JSON catalog path, used only when metadata PostgreSQL is disabled. Relative values remain relative to CWD; use an absolute path operationally.
GEOVAULT_DATA_DIR	If the prior variable is empty, {cleaned value}/versions.json; otherwise CWD-relative data/versions.json.	Relocates only the JSON version catalog.
GEOVAULT_IMPORT_MAX_BYTES	524288000 (500 MiB). Empty, non-integer, zero, or negative values revert to default.	URL and S3 acquisition limit.
GEOVAULT_IMPORT_HTTP_TIMEOUT	15m. Empty, invalid, zero, or negative Go durations revert to default.	URL-download client timeout; not the S3 or reverse-proxy timeout.
QGIS_PUBLISH_URL	Empty.	Exact raster generate/upload endpoint and fallback source for the QGIS service base. Required for raster publish.
QGIS_PUBLISH_BASE_URL	Trimmed explicit value wins. Otherwise derive from QGIS_PUBLISH_URL by removing /projects/generate, /projects/upload, or the suffix from /projects/ onward; otherwise use the URL without a trailing slash.	QGIS project list, history, restore, viewer, and download proxy base.
QGIS_PROJECTS_ROOT	/data/projects.	Root scanned at startup only to remove legacy timestamped QGIS project directories; it does not relocate GeoVault datasets.
TILESERVER_REGISTER_URL	http://localhost:8081/register when empty.	Vector publication registration endpoint.
POSTGIS_SERVICE_URL	http://127.0.0.1:8090/postgis-service; trailing slash removed.	PostGIS Service API proxy base.
POSTGIS_SECRETS_KEY	No default.	Decrypts PostGIS registry passwords; also fallback GeoServer encryption key. Must be 32 raw bytes or base64 encoding of 32 bytes.
GEOVAULT_SECRETS_KEY	Preferred when non-empty, then POSTGIS_SECRETS_KEY.	AES-GCM key for GeoServer passwords. Missing or invalid key causes new values to use plain: storage.
GEOVAULT_GEOSERVER_ALLOW_PRIVATE	False. Only 1, true, or yes (case-insensitive, trimmed) enable it.	Allows literal RFC1918 IPv4 GeoServer URLs. Link-local and known metadata endpoints remain blocked.

GEOVAULT_LISTEN is unused: it appears in a sample comment but no source reads it. The effective listen address is hard-coded :8085, which binds all interfaces. GeoVault defines no effective OAuth/JWT environment variables.

Database and path behavior

DSNs are trimmed and repeatedly unquoted. sslmode=prefer is rewritten to sslmode=disable; use require, verify-ca, or verify-full when PostgreSQL TLS is required. Startup fails if a configured metadata DSN is invalid/unreachable or if no selected auth DSN is reachable.

DATABASE_URL takes storage precedence over JSON: when connected, versions are loaded from and fully rewritten to the versions table. Otherwise the JSON path precedence is GEOVAULT_VERSIONS_JSON → GEOVAULT_DATA_DIR/versions.json → data/versions.json.

These paths are not configurable by those variables:

• dataset versions: hard-coded layouts below /data/projects;
• GDAL sidecar metadata: CWD-relative data/metadata/*.json;
• templates/static files: web/ from CWD, with template lookup also trying the executable directory;
• temporary downloads, extraction, and clip work: the OS temporary directory.

Minimal examples

JSON catalog with a separate Central database:

GEOVAULT_AUTH_DATABASE_URL=postgres://central:[REDACTED]@127.0.0.1:5432/central?sslmode=require
GEOVAULT_VERSIONS_JSON=/var/lib/geovault/versions.json
FEDERATION_SHARED_UI_ROOT=/opt/geovault/shared/ui

Metadata PostgreSQL:

GEOVAULT_AUTH_DATABASE_URL=postgres://central:[REDACTED]@127.0.0.1:5432/central?sslmode=require
DATABASE_URL=postgres://meta:[REDACTED]@127.0.0.1:5432/acugis_meta?sslmode=require
FEDERATION_SHARED_UI_ROOT=/opt/geovault/shared/ui
QGIS_PUBLISH_URL=https://app.example/qgis-publish-service/projects/generate
QGIS_PUBLISH_BASE_URL=https://app.example/qgis-publish-service
GEOVAULT_SECRETS_KEY=[REDACTED_32_BYTE_KEY]
POSTGIS_SECRETS_KEY=[REDACTED_32_BYTE_KEY]

Secret storage

• Database DSNs are environment values.
• pg_connections.password is stored plaintext in metadata PostgreSQL.
• GeoServer passwords are enc: AES-GCM values with a valid key, otherwise plain:.
• PostGIS registry decryption requires the same POSTGIS_SECRETS_KEY as PostGIS Service.
• S3 credentials and ArcGIS tokens arrive in requests/jobs rather than dedicated environment variables.

Protect /etc/geovault.env with least privilege, avoid logging or backing it up in plaintext, set stable encryption keys before creating connections, and rotate both credentials and encryption keys under a tested migration procedure.