Configuration¶
Central has no YAML/TOML/JSON application config file and no CLI flags. Configuration is environment variables only. The systemd unit optionally loads /etc/central.env.
Environment variables¶
Process and assets¶
| Variable | Default | Description |
|---|---|---|
CENTRAL_LISTEN |
:8888 |
HTTP bind address. Empty falls back to :8888. Despite the startup log wording localhost, :8888 typically binds all interfaces. |
CENTRAL_WEB_ROOT |
resolved web |
Override for HTML/JS/CSS templates. Search order when unset: ./web, then <exe-dir>/web, finally literal web. Missing index.html is fatal. |
CENTRAL_THUMBNAILS_DIR |
<webRoot>/thumbnails |
Directory for uploaded portal thumbnails. Created at startup with mode 0755. |
BASE_PATH |
empty | Prefix for all registered routes. / or blank becomes empty; leading slash is ensured and trailing slash stripped. Per-request X-Forwarded-Prefix overrides generated URLs. |
FEDERATION_SHARED_UI_ROOT |
auto-discovered | Shared shell assets root consumed by shared/ui. Candidates include shared/ui, ../shared/ui, ../../shared/ui, and exe-relative paths. |
Database¶
| Variable | Default | Description |
|---|---|---|
CENTRAL_DATABASE_URL |
none | Preferred PostgreSQL DSN. |
DATABASE_URL |
none | Fallback DSN when CENTRAL_DATABASE_URL is empty. |
If neither is set, Central still starts. Portal card persistence, shared authentication, sessions, PATs, and admin APIs remain disabled.
Sessions and cookies¶
| Variable | Default | Description |
|---|---|---|
CENTRAL_SESSION_TTL |
24h (shared/auth.DefaultSessionTTL) |
Preferred session lifetime. Go duration syntax (for example 12h, 90m). Invalid/zero/negative values terminate startup. |
AUTH_SESSION_TTL |
same default | Fallback if CENTRAL_SESSION_TTL is unset. |
ACUGIS_SESSION_COOKIE_DOMAIN |
empty (host-only) | Optional Domain for acugis_session. Use only when cookies must be shared across subdomains and keep consistent across services. |
Cookie fixed attributes (not configurable):
- Name:
acugis_session - Path:
/ - HttpOnly: true
- SameSite: Lax
- Secure: true when request TLS is present or
X-Forwarded-Proto: https
Bootstrap administrator¶
Used only when PostgreSQL is configured and dashboard_users is empty:
| Variable | Default | Description |
|---|---|---|
CENTRAL_ADMIN_USERNAME |
admin (after DASHBOARD_ADMIN_USERNAME fallback) |
Initial admin username |
DASHBOARD_ADMIN_USERNAME |
— | Compatibility fallback for username |
CENTRAL_ADMIN_EMAIL |
empty (after DASHBOARD_ADMIN_EMAIL) |
Initial admin email |
DASHBOARD_ADMIN_EMAIL |
— | Compatibility fallback for email |
CENTRAL_ADMIN_PASSWORD |
generated if unset | Initial admin password |
DASHBOARD_ADMIN_PASSWORD |
— | Compatibility fallback for password |
If no password is provided, Central generates an 18-byte random token and logs the plaintext password once.
Catalog cache¶
| Variable | Default | Description |
|---|---|---|
CENTRAL_CATALOG_CACHE_TTL |
45s |
Per-service, per-cookie catalog cache TTL. Invalid or non-positive values silently revert to 45s (unlike session TTL, which fatals). |
Build-only¶
| Variable | Value | Description |
|---|---|---|
CGO_ENABLED |
0 in build scripts |
Forces non-cgo static-style builds in build.sh / build.ps1 |
Configuration files¶
| File | Role |
|---|---|
deploy/systemd/central.env.example |
Annotated sample for /etc/central.env (documents listen, web root, thumbnails, database URL only) |
deploy/systemd/central.service |
systemd unit referencing EnvironmentFile=-/etc/central.env |
deploy/systemd/geovault.env |
Not loaded by Central. Misplaced GeoVault sample; ignore for Central configuration |
deploy/sql/portal_cards.sql |
Partial SQL for portal_cards only; not a full substitute for runtime EnsureSchema |
Parent repository may also contain operational copies such as ../systemd/envs/central.env. Treat any checked-in credentials as compromised and do not copy them into docs or new environments.
Examples¶
Development (/etc/central.env or shell export)¶
CENTRAL_LISTEN=:8888
CENTRAL_WEB_ROOT=/opt/central/web
CENTRAL_THUMBNAILS_DIR=/opt/central/web/thumbnails
CENTRAL_DATABASE_URL=postgres://central:REDACTED@127.0.0.1:5432/acugis_meta?sslmode=disable
CENTRAL_SESSION_TTL=24h
CENTRAL_CATALOG_CACHE_TTL=45s
CENTRAL_ADMIN_USERNAME=admin
CENTRAL_ADMIN_EMAIL=admin@example.test
CENTRAL_ADMIN_PASSWORD=change-me-now
Subpath mount¶
Cross-subdomain session cookie¶
Only set this when every participating service intentionally shares the cookie domain.
Recommended production settings¶
| Setting | Recommendation |
|---|---|
CENTRAL_LISTEN |
127.0.0.1:8888 when only the local reverse proxy should connect |
| Database TLS | Prefer sslmode=require (or stricter) rather than disable |
CENTRAL_ADMIN_PASSWORD |
Set explicitly before first boot; do not rely on journal-logged generated passwords |
/etc/central.env |
Mode 600, root-owned; avoid committing real values |
| Thumbnails | Keep under /opt/central so systemd ReadWritePaths=/opt/central covers uploads |
| Proxy headers | Ensure the reverse proxy overwrites X-Forwarded-Proto, X-Forwarded-Host, and (if used) X-Forwarded-Prefix |
| Session TTL | Use a finite duration appropriate for your risk model; default is 24h |
Secrets management¶
| Secret | How stored | Notes |
|---|---|---|
| Database password | Environment / DSN | Prefer host secret store or root-only env file |
| Admin bootstrap password | Environment or one-time journal log | Rotate after first login if generated |
| Session tokens | SHA-256 hash in dashboard_sessions |
Raw token only in cookie |
| PATs | SHA-256 hash + 12-char prefix in personal_access_tokens |
Plaintext returned once at creation |
| User passwords | PBKDF2-SHA256 (210000 iterations, 16-byte salt) | Algorithm label pbkdf2-sha256 |
Verified behaviors that require operational care:
- Generated bootstrap admin passwords are logged in plaintext.
- Discovery logs the full outbound
Cookieheader. - Sample env files in the monorepo have included real-looking credentials and
sslmode=disable.
Fixed operational limits (not env-configurable)¶
| Limit | Value |
|---|---|
| Admin/card JSON body | 1 MiB |
| Reorder JSON body | 1 MiB |
| Thumbnail size | 5 MiB (JPEG/PNG/WebP/GIF) |
| Discovery response body | 10 MiB |
| DB startup timeout | 10s |
| Admin discovery context | 15s |
| Catalog aggregate context | 30s |
| Outbound HTTP client timeout | 20s |
Variables not consumed by Central¶
The following appear near Central deployment files but are not read by the Central process:
QGIS_PUBLISH_URLindeploy/systemd/geovault.envGEOVAULT_LISTENcomments in that same file
Downstream discovery URLs are hard-coded in internal/portal/discovery.go and cannot be overridden via environment today.