Configuration reference

GeoSync configuration is split across process environment, PHP files, /etc/default/qz-sync-backend, and generated per-project INI/YAML files. Files under deploy/ and admin/incl/const.php contain deployment-specific credentials in this checkout; never copy their values. Rotate checked-in credentials and inject new secrets with restrictive file permissions.

Environment variables

Variable	Default / behavior
GEOSYNC_AUTH_MODE	Overrides config/auth.php. Supported by the gate: central, local, keycloak; unknown values effectively bypass the Central prepend and are treated as local by the older gate.
CENTRAL_DATABASE_URL	No default. PostgreSQL URL for Central session lookup; implies Central mode. Supports sslmode, default prefer.
GEOSYNC_AUTH_DATABASE_URL	Fallback Central DSN if CENTRAL_DATABASE_URL is empty; does not itself trigger automatic Central-mode detection.
CENTRAL_LOGIN_URL	/login; a next query parameter is appended. A non-empty value implies Central mode.
CENTRAL_LOGOUT_URL	/logout.
CENTRAL_API_ME_URL	Optional first /api/me candidate. Then http://127.0.0.1:8888/api/me and the request host’s /api/me are tried.
GEOSYNC_BASE_PATH	Auto-detected as /geosync-service or /geosync, otherwise empty. Normalize without trailing slash.
ANALYSIS_UPSTREAM	http://127.0.0.1:9096 in both PHP proxies. Note that the supplied analysis systemd unit listens on 127.0.0.1:8081, so it is inconsistent unless overridden.
FORMBUILDER_UPSTREAM	http://127.0.0.1:9095.
QGIS_PUBLISH_URL	http://127.0.0.1:8080/qgis-publish-service.
QGIS_PUBLISH_PROJECTS_ROOT	/var/data/projects.
GEOSYNC_SECRET_KEY_B64	No default; base64 of exactly SODIUM_CRYPTO_SECRETBOX_KEYBYTES bytes. Required only when secrets_Class is used. No schema for its sync_secrets table is supplied.
QFIELDCLOUD_URL, QFIELDCLOUD_API, QFIELDCLOUD_USERNAME, QFIELDCLOUD_PASSWORD	Exported by QField workers/CLI wrappers from project credentials; not global defaults.
PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGTBL	Exported by workers from project configuration.
AG_URL, AG_USERNAME, AG_PASSWORD	Exported by the ArcGIS worker for Python helpers.
FORMBUILDER_LISTEN	Set by the supplied FormBuilder unit to 127.0.0.1:9095; consumed by the external binary, not PHP.
FORMBUILDER_QFIELD_DSN	External FormBuilder database DSN; no PHP default. Its checked-in unit value contains a credential and must be replaced.
HTTP_ADDR	Set by the supplied analysis unit to 127.0.0.1:8081; consumed by the external binary.
TMPDIR	Set to /home/quartz/data/ for the DB Sync unit.
PATH	The FormBuilder unit supplies /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; this is service process setup, not read by GeoSync PHP.
PGDATA	installer/postgres.sh writes /var/lib/postgresql/18/main to /etc/environment; this belongs to the installed PostgreSQL server.
DEBIAN_FRONTEND	Installer scripts transiently set noninteractive; it is an installation control, not a GeoSync runtime option.

deploy/geosync-auth.env.example also mentions ACUGIS_SESSION_COOKIE_DOMAIN, GEOSYNC_SYNC_DATA_ROOT, and GEOSYNC_PUBLISH_PROJECTS_ROOT. GeoSync source does not read them; the first is a Central-side setting and the latter two are currently unsupported documentation/example remnants.

The auth loader reads the first readable file of deploy/geosync-auth.env then /etc/geosync-auth.env, and only fills variables that are not already non-empty in the process. Use /etc/geosync-auth.env only if the checked-in deploy file is absent; process environment takes precedence.

PHP constants

admin/incl/const.php is executable PHP and currently stores secrets in plaintext. Generate a deployment-specific file outside version control or protect and replace it.

Constant	Verified checked-in default / meaning
DB_HOST	localhost
DB_USER	qzs
DB_PASS	Redacted; deployment credential
DB_PORT	5432
DB_NAME	qzs
DB_SCMA	public (name is intentionally misspelled in source and must not be corrected in configuration alone)
SESS_USR_KEY	qz_user; app-install.sh instead generates qzs_user, another inconsistency
SUPER_ADMIN_ID	1
CLUSTERING_ENABLED	false
QUARTZ_SYNC	false; controls optional “Sync Admins” UI
QZ_HOME	/home/quartz
QZ_CONF	/etc/quartz-sync.d
QZ_DATA	/home/quartz/data
DBS_HOME	/home/quartz/db-sync-2.1.1
BACKEND_PIPE	/var/run/qz-sync/.qz-sync.pipe
SHARE_SERVERS, SHARE_PROJECTS, SHARE_GROUPS, SHARE_GSTORES, SHARE_PGLINKS, SHARE_RSYNCS, SHARE_GEONODES	true; allow records to be visible across owners. Super-admin always sees all.
SMTP_HOST, SMTP_USER, SMTP_PASS	Redacted; deployment-specific values
SMTP_PORT	587
DISABLE_OAUTH_USER_CREATION	true
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	Empty by default in generated config.
MICROSOFT_TENANT_ID, MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET	Empty by default in generated config.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Empty by default in generated config.

Additional source constants are fixed, not operator settings: GEOSYNC_PLATFORM_SESSION_COOKIE and GEOSYNC_SESSION_COOKIE are acugis_session; GEOSYNC_RESOURCE_TYPE_SERVICE=service; GEOSYNC_SERVICE_KEY=geosync; GEOSYNC_PROVISION_SOURCE=central_sso; GEOSYNC_AUTH_BOOTSTRAP_DONE is a request guard.

Backend defaults

/etc/default/qz-sync-backend is sourced as shell and loaded by systemd:

QZ_USER='quartz'
QZ_HOME='/home/quartz'
DBS_HOME='/home/quartz/db-sync-2.1.1'
QZ_DATA='/home/quartz/data'
QZ_CONF='/etc/quartz-sync.d'
BACKEND_PIPE='/var/run/qz-sync/.qz-sync.pipe'

Keep these aligned with PHP constants and service units. The backend creates the FIFO with mode 0620, owner root:www-data, and accepts start, stop, restart, status, enable, disable, empty, and clean commands.

Authentication

config/auth.php defaults to central.

• Central: acugis_session contains the raw token; Central stores lowercase SHA-256 in dashboard_sessions.token_hash. GeoSync queries Central first when a DSN exists, then /api/me. The current prepend requires platform admin status/group and creates an in-memory legacy Admin with ID SUPER_ADMIN_ID; it does not use the user-bridge provisioner.
• Local: legacy email/password session in $_SESSION[SESS_USR_KEY]; use only as a controlled break-glass path.
• Keycloak: incl/oidc_config.php defines issuer, client ID/secret, exact redirect URI, optional required_roles_any, redirects, and optional session name. Its checked-in secret and URLs are deployment-specific and must be replaced. The callback maps admin/geosync_admin roles to Admin but decodes access-token claims without cryptographic JWT verification; treat this as legacy and front it with compensating controls until corrected.
• GitHub/Google/Microsoft: constants configure legacy handlers. Their callback URLs are placeholders and some redirects reference viewer.php, which is absent. They are not deployment-ready without code review.

Per-project settings

All project types store name, remote credentials/identifier, PostgreSQL connection, pg_schema, space-separated rsync_ids, and sync_admins.

Setting	New-project default	Meaning
skip_init	false / YAML 0	Do not perform initial copy when true.
force_init	false / YAML 0	QField clears its work directory and drops the configured table; ArcGIS clears work files; Mergin behavior belongs to patched external DB Sync. Destructive.
single_run	false / YAML 0	Exit after one loop.
sleep_time	60 seconds	Poll delay; UI range 10–600. Express defaults to 600 and clamps minimum to 60.
retention	5 for QField/ArcGIS INI	QField snapshot count, UI range 1–10. DB Sync does not support retention and UI forces 1. ArcGIS script does not currently use it.
sync_admins	empty	Optional comma-like consumer setting shown only when QUARTZ_SYNC; worker behavior is not fully defined in this repository.

Type-specific keys:

• QField INI: qf_user, qf_pass, qf_url, qf_proj_id, qf_gpkg, PostgreSQL keys.
• ArcGIS INI: ag_user, ag_pass, ag_url, ag_proj_id, PostgreSQL keys.
• Mergin YAML: mergin.url/username/password, init_from=gpkg, rsync_ids, one PostgreSQL connection (driver=postgres, modified=<schema>, base=<schema>_base, mergin_project=<workspace/project>, sync_file=<name>.gpkg) and the daemon settings above.

Rsync defaults are sync_type=remote, SSH port 22 in the UI/schema context, and usr_grp=www-data:www-data. Local sync requires an already-published target project, writes host/user/password placeholders, and creates excludes for *.qgs and *.qgz. A remote rsync link may be attached to only one project because project_rsync.rsync_id is unique.

Secrets in service, PostGIS, rsync, generated INI/YAML, and generated shell scripts are plaintext. The sodium helper is not integrated into those paths.