Skip to content

Installation

Prerequisites

Source evidence requires:

  • Go 1.22 or newer to build.
  • PostgreSQL reachable for metadata and Central authentication.
  • PostgreSQL client tools psql, pg_dump, pg_restore, vacuumdb, and reindexdb for the corresponding features.
  • GDAL tools ogr2ogr and ogrinfo for vector import.
  • On Linux terminal hosts: journalctl, systemctl, df, free, and ps.
  • A writable backup directory, import directory, and (when network rules are applied) the selected pg_hba.conf.
  • Apache modules proxy, proxy_http, and proxy_wstunnel only for the supplied Apache deployment.

Exact supported PostgreSQL, PostGIS, GDAL, Go patch, operating-system, and Apache versions are not declared in source. Windows PTY code exists, but the supplied systemd/Apache deployment and server-terminal commands are Linux-specific.

Build

The module uses a local replacement, shared => ../shared, so retain the federation sibling layout:

federation/
├── postgis-service/
└── shared/

cd postgis-service
go test ./...
go build -o postgis-service .

build.sh performs only go build -o postgis-service ..

Install the supplied systemd layout

sudo mkdir -p /opt/postgis-service
sudo cp postgis-service /opt/postgis-service/
sudo cp -r web /opt/postgis-service/
sudo cp deploy/postgis-service.env.example /etc/postgis-service.env
sudo cp deploy/systemd/postgis-service.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now postgis-service

The executable resolves templates and static assets from the current working directory first and then the executable directory. The supplied unit sets WorkingDirectory=/opt/postgis-service, starts /opt/postgis-service/postgis-service, restarts always after five seconds, and orders startup after networking and postgresql.service.

Create and permission the configured storage locations for the service account. The supplied unit does not set User, Group, sandboxing, or directory-creation directives, so it runs with systemd's default service identity unless an operator adds overrides.

Configure

At minimum:

POSTGIS_DATABASE_URL=postgres://user:password@127.0.0.1:5432/acugis_meta?sslmode=disable
POSTGIS_AUTH_DATABASE_URL=postgres://user:password@127.0.0.1:5432/acugis_meta?sslmode=disable
POSTGIS_SECRETS_KEY=<32-byte-or-base64-encoded-32-byte-key>
BASE_PATH=/postgis-service
POSTGIS_SERVICE_ADDR=:8090

See Configuration. The process connects, pings, and migrates its metadata database at startup; it also connects and pings the auth database. Failure is fatal.

Verify

There is no unauthenticated health endpoint. Verify through logs and an authenticated request:

sudo systemctl status postgis-service
sudo journalctl -u postgis-service
curl -i --cookie "acugis_session=$ACUGIS_SESSION" \
  http://127.0.0.1:8090/api/connections

A successful startup logs metadata connection and the listening address. See Deployment for the reverse proxy and Authentication before exposing the service.