Skip to content

Installation

Prerequisites

Required to build:

  • Go 1.23+ for qgis-publish-service.
  • Go 1.25+ for qcarta-tiles.
  • The federation repository layout with qgis-publish-service/ and shared/ as siblings.

Required by enabled workflows:

  • QGIS Server, reachable over HTTP or as a local qgis_mapserv.fcgi.
  • PostgreSQL and Central's existing auth schema for authentication and database-backed registries.
  • PostgreSQL with permission to create databases/users and install PostGIS for operational imports.
  • GDAL executables: ogrinfo, ogr2ogr, and gdalinfo.
  • Python 3 with PyQGIS for raster project generation.
  • A writable pg_service.conf shared with QGIS Server for PostGIS project rendering.

The browser UI loads OpenLayers, Materialize, Google Fonts, Proj4js, jsPDF, Turf, Chart.js, and CRS data from public CDNs/services. Production networks must either allow those origins or vendor and update the UI assets.

Build

From qgis-publish-service:

go mod download
go test ./...
go build -trimpath -o qgis-publish-service ./cmd/server

cd qcarta-tiles
go mod download
go test ./...
go build -trimpath -o qcarta-tiles .

There is no repository Makefile, Dockerfile, Compose file, or build/release script.

Local development run

go run ./cmd/server

Without environment overrides, the service:

  • listens on :8080;
  • serves ./html/qgis-publish;
  • stores projects in ./projects;
  • tries QGIS Server at http://127.0.0.1/cgi-bin/qgis_mapserv.fcgi;
  • proxies tile and routing requests to loopback qcarta and OSRM defaults;
  • runs without Central authentication or database registries.

Run qcarta separately:

cd qcarta-tiles
QGIS_SERVER_URL=http://127.0.0.1/cgi-bin/qgis_mapserv.fcgi go run .

QGIS_SERVER_URL has no source default and is required for useful qcarta proxy/render operations.

Host installation

A source-aligned layout for the supplied systemd unit is:

  • main binary: /opt/qgis-publish-service/qgis-publish-service;
  • UI: /opt/qgis-publish-service/html/qgis-publish;
  • shared UI: resolvable beside the working directory/binary, or set FEDERATION_SHARED_UI_ROOT;
  • Python script: /opt/qgis-publish-service/create-qgis-project.py;
  • projects: /var/data/projects;
  • environment file: /etc/qgis-publish-service.env.

The supplied main unit runs as www-data, uses /opt/qgis-publish-service, and permits writes only to /var/data/projects and /var/lib/qgis-publish-service. If versions, runtime datasets, thumbnails, or pg_service.conf live elsewhere, add those paths to ReadWritePaths and grant the service identity access.

The supplied qcarta unit expects:

  • binary: /usr/local/bin/qcarta-tiles;
  • working directory: /var/www/data/qcarta-tiles;
  • service identity: www-data.

Review Deployment before installing either unit.

Initial verification

go test ./...
curl -i http://127.0.0.1:8080/api/discovery
curl -i http://127.0.0.1:8011/api/health

Prefix main-service URLs with BASE_PATH when configured. The main service has no dedicated health endpoint; /api/discovery is a lightweight reachability check, not a dependency health check.