Configuration

Configuration is read from environment variables. The service does not parse a configuration file itself; the supplied systemd unit loads /etc/postgis-service.env.

Environment variables

Variable	Required/default	Source-backed behavior
POSTGIS_DATABASE_URL	Required unless DATABASE_URL is set	Metadata PostgreSQL DSN; first choice.
DATABASE_URL	Fallback	Metadata DSN fallback and last auth DSN fallback.
POSTGIS_AUTH_DATABASE_URL	Required unless a fallback is set	First-choice Central auth/ACL PostgreSQL DSN.
CENTRAL_DATABASE_URL	Auth fallback	Second-choice auth DSN.
POSTGIS_SERVICE_ADDR	:8090	http.ListenAndServe address. No source validation beyond the Go listener.
BASE_PATH	Empty	Mount prefix. / becomes empty; missing leading slash is added; trailing slashes are removed. Both prefixed and unprefixed routes are accepted when non-empty.
POSTGIS_PORTAL_LOGIN_URL	Derived	Central login URL. If absent, uses forwarded/request scheme and host plus /login; a parsed host port such as :8090 is removed.
POSTGIS_SKIP_AUTH	Disabled	1 or case-insensitive true injects admin user dev (ID 1). Development only.
POSTGIS_SECRETS_KEY	Unset	Raw 32-byte or base64-encoded 32-byte AES-GCM key. Unset means new connection passwords are stored as plain:<password>. Invalid non-empty values make writes fail.
POSTGIS_BACKUP_DIR	<cwd>/data/backups; fallback /var/lib/postgis-service/backups only if cwd lookup fails	Root for db-{id}/*.dump.
POSTGIS_IMPORT_DIR	<cwd>/data/imports; fallback /var/lib/postgis-service/imports only if cwd lookup fails	Root for uploaded vector sources.
POSTGIS_HBA_FILE	Empty	Default pg_hba.conf path when a connection has no persisted override. Applying rules fails if neither is set.
TERM	Inherited/default from PTY implementation	Forwarded to Unix PTY sessions when present. It does not alter service routing or database configuration.
FEDERATION_SHARED_UI_ROOT	Empty; then relative/shared/ui discovery	Sibling shared/ui asset root used by /shared/ui/ handlers. When unset, the shared module searches working-directory and executable-adjacent shared/ui paths.

POSTGIS_DATABASE_URL, DATABASE_URL, and auth DSNs accept PostgreSQL URI or libpq forms. Matching outer quote pairs are stripped. URI DSNs must contain a host and database path; libpq DSNs must contain dbname= or database= for metadata. sslmode=prefer is rewritten to sslmode=disable for metadata/auth connections. This downgrade is explicit current behavior.

Forwarded headers

The app consumes:

Header	Use
X-Forwarded-Prefix	Per-request public base path in generated links/templates
X-Forwarded-Proto	Public URL/login construction and request URL scheme
X-Forwarded-Host	Public URL/login construction, WebSocket origin comparison, and r.Host

Forwarded headers are trusted without a proxy allowlist. Bind to a private interface or protect direct access when relying on them.

Registered PostgreSQL connection settings

Each stored server connection has name, host, port (API default 5432 when non-positive), sslmode (empty or prefer is stored as disable), admin_username, admin_password, and an optional persisted hba_file_path.

The editable target-server GUC allowlist is:

Group	Settings
Connectivity	listen_addresses, max_connections
Memory	shared_buffers, work_mem, maintenance_work_mem, effective_cache_size
Performance	max_worker_processes, max_parallel_workers, max_parallel_workers_per_gather, default_statistics_target
Runtime	statement_timeout
Logging	log_statement, log_min_duration_statement

port is explicitly blocked. Updates execute ALTER SYSTEM SET followed by pg_reload_conf(). Some PostgreSQL settings can report pending_restart; the service reports but does not automatically restart PostgreSQL. Memory values require a unit (KB, MB, GB, or TB); log_statement is limited to none, ddl, mod, or all.

Filesystem defaults warning

With the supplied systemd working directory, unset backup/import variables resolve to /opt/postgis-service/data/..., not /var/lib/postgis-service/.... Set the variables explicitly if /var/lib storage is intended.