Skip to content

Installation

GeoSync is Linux-oriented. The supplied installer assumes an apt-based system, Apache, systemd, PostgreSQL/PostGIS, /var/www/html, and root access. It is not idempotent: it creates users, databases, directories, and services without consistently checking whether they exist. Review scripts before running them.

The repository contains deployment-specific secrets. Do not deploy checked-in values. Rotate them, replace admin/incl/const.php and incl/oidc_config.php, and protect generated project files because they contain remote and PostgreSQL passwords.

Requirements

  • PHP 8.1+ with pgsql, curl, yaml, zip, gd, and ssh2; sodium is needed only by secrets_Class.
  • Apache with PHP support, or another PHP-capable web server configured equivalently.
  • PostgreSQL and PostGIS; the installer assumes the local postgres account.
  • systemd, Bash, Python 3, virtualenv, build tools, libpq, SQLite/SpatiaLite, GDAL, rsync, sshpass, unzip, and sudo.
  • Network access to the selected remote platform and any upstream services.
  • A writable QZ_CONF, writable QZ_DATA, readable QZ_HOME/DBS_HOME, and a functional backend FIFO.
  • For QField: qfieldcloud-sdk and geodiff built with PostgreSQL.
  • For Mergin: Mergin DB Sync 2.1.1 as expected by the service file and constants.
  • For ArcGIS: ArcGIS Python API, dask[dataframe], GDAL/ogr2ogr, and geodiff.

Source-assisted installation

Run from a reviewed checkout as root on a disposable/staged Ubuntu-like host:

sudo bash installer/pre-install.sh
sudo bash installer/app-install.sh /var/www/html/geosync

pre-install.sh creates user quartz, builds geodiff 2.0.4, installs QFieldCloud SDK, Mergin DB Sync 2.1.1, and ArcGIS dependencies. app-install.sh installs Apache/PHP packages, creates database/user qzs with a random password, generates a limited admin/incl/const.php, installs scripts and systemd units, and starts qz-sync-backend.

Important caveats:

  • The checked-in installer/setup.sql is not executed by app-install.sh. The web installer executes it, but that path expects the backend and writable directories to exist. Ensure the GeoSync schema is applied exactly once.
  • As checked in, setup.sql creates rsync.local_project_id REFERENCES project(id) before it creates project; PostgreSQL cannot resolve that forward reference. Reorder project before rsync or defer that foreign key in a reviewed deployment copy. Do not silently alter production schema without a backup.
  • app-install.sh copies the checkout recursively, including files not suitable for a web root unless the checkout is curated.
  • Its generated constants omit several constants used elsewhere (SHARE_*, paths, SMTP, and others). Complete configuration from configuration.md.
  • It installs OAuth packages dynamically and then removes root Composer metadata. Dependency reproduction is therefore not fully pinned at repository root.
  • The web installer deletes setup.sql and itself after success.

Manual installation

  1. Provision PostgreSQL/PostGIS and create an application role/database.
  2. Apply installer/setup.sql once to the empty GeoSync database. For upgrades, apply installer/migrations/001_publish_metadata.sql and 002_rsync_local.sql as applicable.
  3. If using the older Central user-provision bridge, apply sql/001_geosync_user_bridge.sql to the GeoSync database. Current geosync_auth_prepend.php instead hydrates a synthetic super-admin and does not provision a row.
  4. If Central service ACL data is required, apply sql/002_geosync_service_resource.sql to the Central metadata database after its resources, resource_permissions, and auth-group tables exist.
  5. Install first-party files in the web root and restrict direct access to configuration, deployment, SQL, logs, and project files.
  6. Create /etc/default/qz-sync-backend from installer/qz-sync-backend.default; create QZ_CONF, QZ_CONF/rsync.d, QZ_DATA, and /var/run/qz-sync with coordinated www-data/quartz access.
  7. Install reviewed scripts from usr-local-bin/ under /usr/local/bin, and install reviewed units from deploy/ under /etc/systemd/system.
  8. Build/install external worker dependencies, then run systemctl daemon-reload, enable/start qz-sync-backend, and configure authentication and constants.
  9. Configure the web server and TLS using deployment.md.

Do not run both schema setup paths against the same initialized database: the base schema uses non-idempotent CREATE TYPE and CREATE TABLE.

Build and local development

There is no application build step. PHP and static assets are checked in. External worker “build” means compiling geodiff and preparing Python environments; use installer/pre-install.sh as a reference, not an unattended production recipe.

For UI-only local work, serve the repository with PHP after supplying a disposable PostgreSQL schema and safe constants:

php -S 127.0.0.1:8080

The built-in server does not reproduce Apache auto_prepend_file, URL mounting, systemd, FIFO permissions, or worker execution. Set GEOSYNC_AUTH_MODE=local only on an isolated development host and create a local admin through a reviewed setup path.

Docker

No Dockerfile or Compose file exists in GeoSync. Container commands, images, volumes, health checks, and entrypoints are therefore unsupported and intentionally not invented. A containerization effort must account for Apache/PHP, PostgreSQL/PostGIS, systemd/FIFO control, Python workers, writable project/config volumes, and host service management; systemd inside a single application container is not a drop-in equivalent.

Production deployment

The verified production model is Apache/PHP plus host systemd services on Linux. Complete the manual installation, replace all deployment credentials, disable displayed PHP errors, restrict sensitive web paths, terminate TLS, establish database/filesystem backups, and validate each enabled worker type before accepting traffic. Use the full deployment guide for service units, reverse proxies, TLS, scaling limits, health checks, logging, and monitoring.

Installation failures

  • PHP parse errors around str_* functions or Composer platform check failure: install PHP 8.1+.
  • yaml_*, ZipArchive, pg_connect, cURL, sodium, or SSH2 missing: install the corresponding PHP extension and restart the PHP handler.
  • Schema already exists: stop; do not rerun setup.sql. Determine migration state and apply only missing migrations.
  • Backend check fails: verify /etc/default/qz-sync-backend, the FIFO parent directory, service logs, and user/group permissions.
  • Worker command missing: verify virtual environments, /usr/local/bin/geodiff, GDAL, and the exact paths in the units.
  • Composer/OAuth failure: the checked-in vendor/ tree exists, but root dependency metadata is absent; do not assume composer install at repository root is reproducible.