Self-hosting

Choose a deployment topology

Deployment overview compares the supported packaged Docker and packaged native installation shapes.

Choosing the topology first avoids confusing the packaged development-mode single-host evaluation profile with the external-provider or native production shapes and unproven multi-node storage.

Use it during architecture review, capacity planning, or before changing an existing installation shape.

Requirements for Self-hosting

• Prerequisite — An inventory of provider, storage, networking, backup, and operator capabilities.
• Prerequisite — A decision among single-host evaluation, external-provider Docker production, native systemd production, or future fenced multi-node placement.
• Required value — Expected active projects, request rate, storage growth, recovery objectives, and public origins.
• Required value — Ownership for PostgreSQL, S3, email, TLS, secrets, monitoring, and incident response.

Choose an installation shape

• Use ffdb-compose-bundle-VERSION.tar.gz with the explicit single-host profile for loopback-only evaluation, or with the external profile and operator-managed PostgreSQL, HTTPS S3, real email, and TLS for internet production.
• Use an architecture-matched ffdb-native-linux-ARCH-VERSION.tar.gz component artifact for advanced systemd installation when every dependency and service boundary is operator-managed.
• Select server artifacts only from an announced tag on the canonical Forever-Frameworks-LLC/ffdb GitHub Releases page; do not infer availability from an example version.
• Install all public @ffdb packages from npm at the exact server version. Use checksum-listed tarballs from the matching server tag for verified offline installation.
• Use Kubernetes only after project placement gives each stateful API/worker pod a disjoint project database set.

Service topology

• apps/api combines the asynchronous Rust HTTP/control-plane service with the node-local SQLite worker supervisor; the current release runs one API owner per routed project set.
• apps/database-worker executes project SQL inside an isolated process boundary.
• apps/sync-worker performs asynchronous sync and maintenance work.
• PostgreSQL holds control-plane state; project SQLite files and encrypted backups use separate durable volumes.
• An S3-compatible provider stores object bytes while project SQLite stores authorization metadata.

Durable state map

• PostgreSQL: organizations, projects, credentials, routing, jobs, audit state, and platform migrations.
• Project root: one private SQLite application database per project.
• Backup root: encrypted FFDB backup envelopes; plaintext exists only in guarded transient worker staging.
• S3-compatible provider: object bytes only; SQLite remains authoritative for metadata and authorization.
• Sync state root: durable maintenance checkpoints, not user data or a second authorization path.

Production baseline

Terminate TLS before FFDB, use a narrow trusted proxy boundary, keep provider credentials server-side, isolate project and backup storage, and configure the public S3 endpoint separately from the internal endpoint.

Contributor source workflow

A source checkout is the supported fallback for development, auditing, and release engineering—not an operator installation. It requires Rust 1.96.1, Node 24+, pnpm 11.6, Docker, and Compose. The Makefile is the universal repository entry point: build compiles every Rust and TypeScript target, verify runs the complete quality suite, and compose-rebuild creates the contributor stack from the checkout.

corepack enable
pnpm install --frozen-lockfile
make build
make verify
make compose-rebuild
make status

# Compiled nginx gateway built from this checkout.
curl --fail http://127.0.0.1:5173/readyz
# Contributor-only direct Axum diagnostic.
curl --fail http://127.0.0.1:8080/readyz

Self-hosting workflow

• 1. Compare single-host evaluation, external-provider Docker production, and native systemd production against the team's operating model.
• 2. Map every durable state location and its backup owner.
• 3. Confirm that each API node owns a disjoint project database set before scaling.
• 4. Record the chosen path and acceptance gates.

Verify self-hosting

One supported topology is selected with explicit durable-state, ingress, upgrade, and recovery ownership.

Troubleshoot self-hosting

• The design mounts one project database into multiple unfenced writers — redesign placement before deployment.
• The only backup is a copied live SQLite file — use the encrypted FFDB backup workflow instead.

Continue from Self-hosting

• Open the selected install guide.
• Complete Configuration and Production security.