Deploying Freehold

01Architecture at a glance

Freehold is a three-tier application that depends on three external services you provide: PostgreSQL, S3-compatible object storage, and an OIDC identity provider.

02Prerequisites

Tooling (build machine)

External services to provision first

03Provision the external services

3.1 — PostgreSQL

Create a database and a role. The role must be allowed to run CREATE EXTENSION — migrations install uuid-ossp and pg_trgm automatically.

CREATE ROLE freehold WITH LOGIN PASSWORD 'change-me';
CREATE DATABASE freehold OWNER freehold;

# connection string
postgres://freehold:change-me@db-host:5432/freehold?sslmode=require

3.2 — Object storage (S3-compatible)

Create a bucket (e.g. freehold-files) and an access-key / secret-key pair scoped to it. Note the endpoint and region. Keep path-style addressing on for B2, Wasabi, and MinIO.

3.3 — OIDC provider (confidential client)

Register a confidential OAuth2/OIDC application. Record the issuer URL, client ID, and client secret.

04Deploy the backend (Go API)

A single statically-linked binary plus a migrate helper and the migrations/ directory. Run it as a systemd service behind a TLS reverse proxy.

4.1 — Build

# API server (static Linux binary)
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  go build -o bin/freehold ./cmd/freehold

# Migration tool (needs the freehold_tools build tag)
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  go build -tags freehold_tools -o bin/migrate ./cmd/migrate

4.2 — Configure (.env)

The server fails fast if OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, STORAGE_ENDPOINT, or STORAGE_BUCKET are missing.

SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_BODY_LIMIT=524288000          # 500 MB

DATABASE_URL=postgres://freehold:***@db-host:5432/freehold?sslmode=require

OIDC_ISSUER_URL=https://auth.example.com/application/o/freehold/
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URL=https://freehold.example.com/callback

STORAGE_ENDPOINT=https://s3.us-west-000.backblazeb2.com
STORAGE_REGION=us-west-000
STORAGE_BUCKET=freehold-files
STORAGE_ACCESS_KEY=your-access-key
STORAGE_SECRET_KEY=your-secret-key
STORAGE_USE_PATH_STYLE=true
STORAGE_PRESIGN_DURATION=15m

CORS_ALLOWED_ORIGINS=https://freehold.example.com

4.3 — Run migrations

Idempotent — applied versions are tracked in a schema_migrations table. Use ./migrate down to roll back one step.

DATABASE_URL='postgres://freehold:***@db-host:5432/freehold' \
  ./migrate up

4.5 — systemd + 4.6 reverse proxy

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/freehold
ExecStart=/opt/freehold/freehold
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

client_max_body_size 500m;

location / {
  proxy_pass http://127.0.0.1:8080;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto
    $scheme;
}

Keep the proxy body-size limit in sync with SERVER_BODY_LIMIT so large uploads aren't rejected. Health check: GET /api/v1/health → {"status":"ok"}

05Deploy the web frontend (React)

A static Vite build. The reference target is Cloudflare Pages (which also runs the bundled Functions); a netlify.toml is included, and any static host works.

cd frontend
npm install
npm run build        # → dist/

wrangler pages deploy dist/ \
  --project-name freehold

06Deploy the mobile PWA (optional)

A standalone, touch-optimized PWA on the same API. Build it, serve dist/ as a static SPA, and replace the placeholder icons in mobile/public/ before production.

cd mobile
npm install
npm run build        # → dist/

07Environment variable reference

S3_* and STORAGE_* names are interchangeable; if both are set, S3_* wins.

08One-command deploy (maintainer reference)

The repo ships scripts that automate the maintainer's own deployment. They are environment-specific — review and adapt hostnames, paths, and the SSH user before use.

09Verification checklist

10Troubleshooting