Skip to content

Installation

Requirements

Requirement Notes
Go 1.22+ Matches go.mod (go 1.22)
Sibling module ../shared Required by replace shared => ../shared
PostgreSQL Optional for process start; required for portal cards, sessions, PATs, and admin APIs
Linux/Unix or Windows Build scripts provided for both
Reverse proxy (production) Parent repository uses Apache for TLS and routing; Central itself serves plain HTTP

Dependencies

Direct Go modules:

Module Purpose
github.com/jackc/pgx/v5 v5.5.5 PostgreSQL pool and queries
shared v0.0.0 Local auth/UI shared packages (../shared)

Indirect modules include pgx helpers and golang.org/x/crypto, sync, and text.

Browser assets loaded by templates (not Go modules):

  • Materialize CSS/JS 1.0.0 from cdnjs
  • Google Fonts / Material Icons

There is no npm/package.json dependency tree in Central.

Installation

Docker installation

Not verified. No Dockerfile, Containerfile, or Compose file exists under central/ or as a Central-specific image in the parent repository. Do not invent a container workflow from sibling services.

Manual installation

  1. Clone the federation monorepo so that central/ and shared/ are siblings.
  2. Install Go 1.22 or newer.
  3. Optionally provision a PostgreSQL database (example DSN form only):
postgres://USER:PASSWORD@127.0.0.1:5432/acugis_meta?sslmode=prefer
  1. Create /etc/central.env from the example:
sudo cp deploy/systemd/central.env.example /etc/central.env
sudo chmod 600 /etc/central.env
# edit CENTRAL_DATABASE_URL, CENTRAL_LISTEN, etc.
  1. Build and install the binary and web assets (typical production layout):
cd central
./build.sh
sudo mkdir -p /opt/central
sudo cp central /opt/central/central
sudo cp -a web /opt/central/web
# also ensure shared UI assets are reachable; FEDERATION_SHARED_UI_ROOT may be required
sudo cp deploy/systemd/central.service /etc/systemd/system/central.service
sudo systemctl daemon-reload
sudo systemctl enable --now central
  1. Place Central behind Apache (or another reverse proxy). Parent-repo configs under ../apache.conf/ already route /, /login, /logout, and selected /api/* paths to 127.0.0.1:8888.

Building from source

Unix/Linux/macOS:

cd central
./build.sh
# produces ./central

Windows (PowerShell):

cd central
.\build.ps1
# produces .\central.exe

Both scripts set CGO_ENABLED=0 and use -trimpath -ldflags "-s -w".

Development without a packaged binary:

cd central
go run .

CENTRAL_WEB_ROOT resolution searches ./web then <executable-dir>/web, so go run . works when launched from the Central directory.

Running locally

Minimal local run (no database; portal/auth disabled):

cd central
go run .
# listens on :8888
curl http://127.0.0.1:8888/api/health

Local run with PostgreSQL:

export CENTRAL_DATABASE_URL='postgres://USER:PASSWORD@127.0.0.1:5432/acugis_meta?sslmode=disable'
export CENTRAL_ADMIN_USERNAME=admin
export CENTRAL_ADMIN_PASSWORD='choose-a-strong-password'
cd central
go run .

On first database bootstrap with an empty user table, Central creates a local administrator. If no password is set, it generates one and logs the plaintext password.

Production deployment

Verified production path:

Item Value
Binary /opt/central/central
Working directory /opt/central
Web assets /opt/central/web (or CENTRAL_WEB_ROOT)
Environment file /etc/central.env (optional; unit uses EnvironmentFile=-/etc/central.env)
User/group www-data
Unit deploy/systemd/central.service (also mirrored under ../systemd/)
Logs journald identifier central

See Deployment for Apache, TLS, scaling, and monitoring details.

Common installation problems

Symptom Likely cause Remedy
index.html not found under web Wrong working directory or missing assets Run from central/, set CENTRAL_WEB_ROOT, or install web/ beside the binary
Portal APIs return empty notes or 503 No CENTRAL_DATABASE_URL / DATABASE_URL Set a reachable PostgreSQL DSN and restart
Startup fatal on session TTL Invalid CENTRAL_SESSION_TTL / AUTH_SESSION_TTL Use Go duration syntax such as 24h
Shared UI missing shared/ui not found Keep monorepo layout or set FEDERATION_SHARED_UI_ROOT
Module resolve failure for shared Missing sibling directory Build from federation checkout containing ../shared
Admin login rejected Auth DB empty bootstrap failed, wrong password, or disabled user Inspect journal for bootstrap password log; verify dashboard_users
Proxy 404 for /api/catalog Apache copy missing catalog route Compare with ../apache.conf/000-default-le-ssl.conf which includes /api/catalog

For more diagnostics, see Troubleshooting.