FT Pages

Self-hosted Pages host for Forgejo.

FT Pages receives Forgejo push webhooks, builds static sites in isolated Docker build containers, and serves releases through Caddy.

---

Current Architecture (Phase C)

Push to Forgejo
    │
    ▼
Forgejo Webhook (POST /api/webhook)
    │
    ▼
FT Pages Controller Logic (inside ft-pagesd)
    ├─ verify HMAC signature
    ├─ create deploy job
    ├─ local scheduler dequeues queued job
    └─ assigns to built-in local host
    │
    ▼
FT Pages Agent Logic (same ft-pagesd process, local host)
    ├─ clone repo
    ├─ read pages.yml
    ├─ run build in ephemeral Docker container
    ├─ create release + switch current symlink
    └─ regenerate/reload Caddy config
    │
    ▼
Visitors

Today this still runs on a single host, but the controller/agent model is now documented and implemented as a foundation for multi-host scheduling later.

Important

• Production deployment is bare-metal (install.sh)
• Docker is used for:
  • isolated per-project builds
  • local development stack in deploy/docker-compose.yml
• Frontend is optional/deferred. API-first control-plane endpoints are the source of truth.
• Forgejo Actions are optional/legacy for deployment. Webhooks are the recommended flow.
• Lifecycle policy defaults:
  • ttl_days=7
  • grace_days=3
  • at TTL expiry: project is disabled and owner notification is attempted
  • after grace expiry: project is deleted by lifecycle worker policy

---

Features

• Webhook-driven deployments (POST /api/webhook)
• Runner-style host registration for agents (/api/agent/* + /api/control/hosts*)
• Deploy job queue model with control visibility/retry (/api/control/jobs*)
• HMAC signature verification for webhook security
• Per-repo pages.yml config
• Ephemeral Docker build sandbox per deployment
• Release history with instant rollback
• Automatic retention cleanup
• Caddy config generation + reload
• Legacy direct artifact deploy endpoint (POST /api/deploy)
• Control-plane endpoints for lifecycle/settings/events (/api/control/*)
• Lifecycle renew via successful deploy or manual POST /api/projects/{id}/renew

---

Quick Start (Production)

1) Run installer on FT Pages host

chmod +x install.sh
sudo ./install.sh

Installer will:

• install Docker, Caddy, and build dependencies
• download ft-pagesd binary from Nexus Raw (ft-binaries)
• verify checksum (.sha256)
• create /opt/ft-pages/.env
• create and start ft-pagesd systemd service

2) Configure Forgejo webhook

In repository settings:

• Target URL: https://api.pages.yourdomain.com/api/webhook
• Method: POST
• Content-Type: application/json
• Secret: FT_PAGES_WEBHOOK_SECRET value from /opt/ft-pages/.env
• Trigger: Push events

3) Add pages.yml to repository root

pages:
  enabled: true
  name: my-site
  domain: my-site.pages.yourdomain.com
  build_command: npm ci && npm run build
  build_dir: dist
  retention: 10

4) Push

Push commit. FT Pages builds and deploys automatically.

A successful deploy also renews lifecycle expiry for that project (sets lifecycle back to active and recomputes TTL).

---

Versioned Binary Publishing

Repo includes Forgejo workflow:

• .forgejo/workflows/build.yml

It publishes ft-pagesd binary + checksum to:

• https://nexus.ftmahringer.com/repository/ft-binaries/ft-pagesd/...

Semver behavior:

• Tag vX.Y.Z publishes to: vX.Y.Z, vX.Y, vX, latest
• main branch publishes snapshot: v0.0.0-dev.<run_number>

---

Local Development

Use deploy/docker-compose.yml for local testing only.

# API-only (recommended)
docker compose -f deploy/docker-compose.yml up -d ft-pages-api

# optional: include deferred frontend service
# docker compose -f deploy/docker-compose.yml up -d ft-pages-api ft-pages-ui

# optional full proxy stack
docker compose -f deploy/docker-compose.yml --profile full up -d

---

Documentation

• docs/installation.md — bare-metal install
• docs/webhook.md — webhook setup and pages.yml
• docs/configuration.md — env vars and Phase C data model notes
• docs/api.md — API endpoints (including agent + host/job control APIs)
• docs/controller-agent.md — controller/agent architecture, registration flow, roadmap
• docs/caddy.md — Caddy behavior
• docs/forgejo-actions.md — legacy/optional flow

---

License

MIT (LICENSE)