Skip to content

GeoSync developer documentation

Overview

Purpose

GeoSync is a PHP/PostgreSQL administration application that copies field-project data into PostGIS and manages each synchronization job through systemd. The source supports QFieldCloud (qf), Mergin Maps DB Sync (db), and ArcGIS file geodatabases (gdb). It can also copy synchronized files with rsync, inspect spatial data, proxy FormBuilder and analysis services, publish QGIS projects through qgis-publish-service, and manage users and integration records.

Security: checked-in configuration contains deployment-specific database, SMTP, OAuth/OIDC, and service credentials. Values are intentionally not reproduced here. Treat them as exposed: rotate them and override or replace the configuration before deployment.

Major features

  • Register QFieldCloud, Mergin Maps, or ArcGIS services and PostGIS targets.
  • Create project INI/YAML configuration and control templated sync services.
  • Poll remote projects, retain GeoPackage snapshots, calculate changes with geodiff, and apply them to PostGIS.
  • Run Mergin DB Sync, convert ArcGIS geodatabases with GDAL, and copy images.
  • Configure remote SSH/rsync or local published-project copies.
  • Browse PostGIS tables and GeoJSON; proxy allow-listed analysis and FormBuilder operations.
  • Publish or republish synchronized QGIS bundles and record publisher metadata.
  • Authenticate locally, through Central platform SSO, through legacy Keycloak OIDC, or through legacy social OAuth handlers.

Architecture summary

Apache/PHP is the control plane. It authenticates browser sessions, stores metadata in PostgreSQL, writes project INI/YAML files, and sends constrained commands through a named pipe to a root-owned backend. The backend controls per-project systemd workers, which call provider tools and synchronize files into target PostGIS databases. Optional sibling services provide analysis, form generation, Central authentication, and QGIS publishing.

Typical workflows

Typical project flow:

  1. Add a remote service and a PostGIS link.
  2. Create a project manually or with the QField Express workflow.
  3. GeoSync writes /etc/quartz-sync.d/<id>.ini or <id>.yaml.
  4. Enable/start <type>-sync@<id>.service from the UI.
  5. The worker downloads or converts data and updates PostGIS.
  6. Optional rsync scripts run after a sync; optional QGIS publishing sends a bundle to the publisher service.

Technology stack

  • Server UI and actions: PHP using pgsql, sessions, cURL, YAML, ZipArchive, GD, SSH2, and optionally sodium.
  • Database: PostgreSQL/PostGIS.
  • Workers: Bash, Python virtual environments, qfieldcloud-sdk, Mergin DB Sync 2.1.1, ArcGIS Python API, GDAL, and Mergin geodiff 2.0.4.
  • Process control: systemd templates plus a named-pipe manager.
  • Front end: server-rendered PHP, JavaScript, Materialize/Bootstrap and bundled browser libraries.
  • Integrations: Central platform auth, QFieldCloud, Mergin Maps, ArcGIS, GeoServer, SSH/rsync, QGIS Publish, FormBuilder, and analysis service.

PHP 8.1 or newer is required by the committed Composer platform check; source also uses str_starts_with() / str_contains(). The installer only checks “greater than 5”; that check is obsolete and is not a reliable requirement.

Repository structure

  • admin/: pages, POST action handlers, domain classes, and generated incl/const.php.
  • api/: authenticated allow-list proxy and PHP analysis helpers.
  • analysis/, formbuilder/: authenticated reverse proxies and local analysis assets.
  • auth/, incl/, config/: session, Central SSO, service ACL, and legacy OIDC support.
  • installer/: Ubuntu-oriented package/build scripts, schema, migrations, and service templates.
  • deploy/: current service units and auth environment examples.
  • usr-local-bin/: installed worker and backend scripts.
  • sql/: optional Central user bridge and Central service-resource SQL.
  • vendor/, assets/: checked-in PHP and browser dependencies.

Key concepts

  • Service: remote QFieldCloud, Mergin, or ArcGIS endpoint and credentials.
  • PostgreSQL link: destination host, database, user, password, and default port 5432.
  • Project: joins one service to one PostGIS link, schema, remote project identifier, and GeoPackage.
  • Daemon settings: initialization behavior, polling interval, retention, and optional file consumers.
  • Rsync link: post-sync remote SSH copy or local copy into an already-published project.
  • Ownership/sharing: records have owner_id; SHARE_* constants control cross-owner visibility, while the super-admin ID bypasses it.
  • Central mode: validates the acugis_session cookie and currently requires a platform administrator before hydrating a synthetic legacy Admin session.

Documentation

Verified limitations

There is no Dockerfile or Compose file in this repository, no first-party automated test suite, no declared public API specification, and no repository tags. Nginx configuration, a production backup policy, metrics, readiness endpoints for the PHP application, and horizontal-scaling support are not supplied. See the deployment and development guides for safe, explicitly marked operator patterns.