Configuration¶

Configuration is read from process environment variables. The application does not load .env files itself; systemd's sample unit optionally loads /etc/qgis-publish-service.env.

Secret handling: tracked env/unit/application samples contain credential-like values. Values are omitted here. Rotate them before production and use placeholders such as postgres://app:[REDACTED]@db/app and [REDACTED_TOKEN].

Main service¶

HTTP, files, and shared UI¶

Variable	Source default	Required and behavior
`LISTEN`	`:8080`	Optional HTTP bind address. No TLS listener is implemented.
`BASE_PATH`	empty	Optional URL prefix; trailing `/` is removed. Example: `/qgis-publish-service`.
`PROJECTS_ROOT`	`./projects`	Optional path; must be writable for publishing and updates.
`UI_ROOT`	`./html/qgis-publish`	Optional static UI path.
`FEDERATION_SHARED_UI_ROOT`	auto-searches `shared/ui` beside CWD/binary	Optional override used by imported `shared/ui`.
`BROWSER_MAP_THUMBNAILS_DIR`	`$UI_ROOT/thumbs/browser-maps`	Optional writable thumbnail path.
`INGEST_TEMP_ROOT`	OS temp directory plus `acugis-ingest`	Optional temporary ingest-session storage. Session deletion removes its directory.
`GEOVAULT_PROJECT_VERSIONS_ROOT`	`/data/geovault/project_versions`	Optional immutable project snapshot root; required to be writable for update/restore workflows.
`RUNTIME_DATASETS_ROOT`	`./runtime-datasets`	Optional archive/generated-project root for operational imports.

QGIS, GDAL, and generation¶

Variable	Source default	Required and behavior
`QGIS_MAPSERV_URL`	`http://127.0.0.1/cgi-bin/qgis_mapserv.fcgi`	Used when `QGIS_MAPSERV_BIN` is empty.
`QGIS_MAPSERV_BIN`	empty	Optional local CGI executable; when set, takes precedence over HTTP proxying. CGI calls time out after 5 minutes and cap stdout at 512 MiB.
`QGIS_MAP_PATH_PREFIX`	`/var/data/projects`	Filesystem prefix used in QGIS `MAP=` values; must match QGIS Server's view of project storage.
`PG_SERVICE_FILE`	`/etc/postgresql-common/pg_service.conf`	Optional libpq service file path read and atomically edited by the API. QGIS Server must read the same file independently.
`GDALINFO_BIN`	`gdalinfo`	Optional executable override for raster inspection. `ogrinfo` and `ogr2ogr` are fixed command names and must be on `PATH`.
`PYTHON_BIN`	`python3`	Optional PyQGIS interpreter.
`CREATE_QGIS_PROJECT_SCRIPT`	auto-detected, then `create-qgis-project.py`	Optional path to the raster project generator.
`QGIS_PREFIX_PATH`	inherited; `/usr` injected into the generator child if absent	Optional PyQGIS runtime setting.
`QT_QPA_PLATFORM`	inherited; `offscreen` injected into the generator child if absent	Optional headless Qt setting.
`FORMS_PARSER_DEBUG`	enabled	Optional. `0`, `false`, or `no` disables verbose form-parser logs; any other non-empty value enables them.

Database and authentication¶

Variable	Source default	Required and behavior
`QGIS_AUTH_DATABASE_URL`	none	Highest-precedence Central PostgreSQL URL.
`CENTRAL_DATABASE_URL`	none	Second-precedence Central URL.
`DATABASE_URL`	none	Last-precedence Central URL. If all three are absent/unreachable, Central auth and all registry-backed features are disabled while the process continues.
`ACUGIS_SESSION_COOKIE_DOMAIN`	empty/host-only	Imported shared-auth cookie issuance setting. This service validates the `acugis_session` cookie but exposes no login/session-creation route, so Central normally owns issuance.
`RUNTIME_PG_ADMIN_DSN`	falls back through the three Central URLs	Required for legacy operational GeoPackage import. Despite its name and the tracked sample, source accepts only `postgres://` or `postgresql://` URLs; libpq `host=...` DSNs fail as “unsupported database URL scheme.”
`RUNTIME_PG_USER`	admin URL user	Optional runtime database role override.
`RUNTIME_PG_PASSWORD`	admin password only when runtime/admin usernames match	Required if the selected runtime role needs a password and cannot reuse the admin credential.
`RUNTIME_PG_SSLMODE`	admin URL `sslmode`; ultimately `disable` when absent	Optional runtime connection mode.

The runtime import code creates a database and may create a cluster role, enables PostGIS, grants broad privileges, imports through ogr2ogr, and writes credentials to PG_SERVICE_FILE. Use dedicated least-privilege credentials and protect that file.

External services¶

Variable	Source default	Required and behavior
`QCARTA_TILES_URL`	`http://127.0.0.1:8011`	Tile/cache reverse proxy, seed, metadata prewarm, reload, and purge target.
`QCARTA_CACHE_PURGE_TOKEN`	empty	Shared secret sent to qcarta on project purge. Main-service purge is skipped when empty.
`OSRM_ROUTING_URL`	`http://127.0.0.1:5000`	Target for the `/routing/` reverse proxy.
`GEOVAULT_URL`	`http://127.0.0.1:8085`	Server-side GeoVault quick-import/browse target.
`GEOVAULT_PUBLIC_PATH`	`/geovault`	Browser-facing same-origin GeoVault mount.
`GEOVAULT_BASE_PATH`	empty	Optional prefix tried first for one GeoVault PostGIS preview path; source also tries `/geovault` and unprefixed paths.

Bundled qcarta-tiles¶

Variable	Source default	Required and behavior
`QGIS_SERVER_URL`	none	Required for useful operation. Base URL used for upstream QGIS requests.
`QCARTA_LISTEN`	`127.0.0.1:8011`	Optional bind address. Loopback is the safe default.
`QCARTA_CACHE_DIR`	`/var/www/data/qcarta-tiles/cache_data`	Optional disk cache root; must be writable.
`QCARTA_CACHE_TTL`	`604800` seconds (7 days)	Optional integer seconds. Invalid values fall back to 7 days.
`QCARTA_CACHE_PURGE_TOKEN`	none	Required only for `POST /admin/cache/purge`; absence makes that endpoint return 500. Must match the main service.
`QCARTA_CACHE_DEBUG`	off	Set exactly `1` for full normalized query/cache key/path logs; these may expose sensitive filter data.
`QCARTA_DISABLE_CACHE`	off	Set exactly `1` to bypass response and metadata caches.
`QCARTA_CANONICAL_TILE_CACHE_WMS`	off	Set exactly `1` to route eligible tile-like WMS GetMap requests through the canonical XYZ path.
`QCARTA_METATILE_SIZE`	`4`	Integer >=1; invalid values use 4.
`QCARTA_METATILE_BUFFER`	`64` pixels	Integer >=0; invalid values use 64.
`QCARTA_DISABLE_METATILES`	off	Set exactly `1` for one upstream 256×256 render per tile. Size `1` plus buffer `0` has the same effect.
`QCARTA_TILE_OVERSAMPLE`	`1`	Integer factor. Source accepts 1–8 and caps larger values to 8, although its comment lists 1, 2, 4, and 8. Upstream tiles are downsampled to 256×256.

The qcarta systemd sample mentions QCARTA_WWW_DIR and QCARTA_LAYER_CACHE_REFRESH_SEC, but no current Go source reads either variable. They have no verified effect and should not be relied upon.

Development-only environment¶

TEST_POSTGRES_URL is read only by an opt-in PostgreSQL relation scan test. It is not runtime configuration.

Example¶

LISTEN=127.0.0.1:8080
BASE_PATH=/qgis-publish-service
PROJECTS_ROOT=/var/data/projects
QGIS_MAP_PATH_PREFIX=/var/data/projects
QGIS_AUTH_DATABASE_URL=postgres://qgis_publish:[REDACTED]@127.0.0.1:5432/central?sslmode=require
QCARTA_CACHE_PURGE_TOKEN=[REDACTED_TOKEN]