Configuration

Define the deployment boundary

Configuration defines the server, provider, secret, and client values that form FFDB trust boundaries.

Several similar-looking URLs and keys have intentionally different exposure and rotation rules.

Use it before first start, when adding a node, or during a reviewed rotation or provider migration.

Requirements for Configuration

• Prerequisite — Provisioned PostgreSQL, S3-compatible storage, email delivery, DNS, and TLS.
• Prerequisite — A secret manager or a protected release-environment file workflow.
• Required value — Public and internal endpoints, allowed origins, database URL, node ID/name, filesystem roots, worker limits, independent master/backup/cursor/bootstrap keys, S3 credentials, and email sender.
• Required value — For clients: base URL, project ID, session store, and trusted-only developer key when applicable.

Generate independent secrets

FFDB validates secret length at startup. Generate each value independently and store it in a secret manager; never copy the disposable values from compose.yaml into production.

# FFDB_MASTER_KEY: exactly 32 random bytes, base64 encoded
openssl rand -base64 32

# FFDB_BACKUP_MASTER_KEY: a different 32-byte base64 value
openssl rand -base64 32

# FFDB_CURSOR_HMAC_KEY: at least 32 random characters
openssl rand -hex 32

# FFDB_BOOTSTRAP_TOKEN: at least 32 random characters
openssl rand -hex 32

Server configuration groups

• HTTP: FFDB_HTTP_BIND, FFDB_PUBLIC_BASE_URL, an exact comma-separated FFDB_CORS_ALLOWED_ORIGINS list, and the narrow FFDB_TRUSTED_PROXY_CIDRS boundary.
• PostgreSQL: FFDB_DATABASE_URL and FFDB_POSTGRES_MAX_CONNECTIONS.
• Workers and usage: FFDB_NODE_ID, FFDB_NODE_NAME, FFDB_DATABASE_ROOT, FFDB_BACKUP_ROOT, FFDB_METRICS_ROOT, FFDB_DATABASE_WORKER, FFDB_WORKER_MAX_PROCESSES, and FFDB_WORKER_QUEUE_CAPACITY. A project worker executes one framed request at a time.
• Security: FFDB_MASTER_KEY, FFDB_BACKUP_MASTER_KEY, FFDB_CURSOR_HMAC_KEY, and FFDB_BOOTSTRAP_TOKEN.
• Storage: internal and browser-visible S3 endpoints, region, bucket, access key, secret key, and the private-network opt-in.
• Email: production uses FFDB_EMAIL_TRANSPORT=resend, FFDB_RESEND_API_KEY, and FFDB_EMAIL_FROM.

Production validation

• FFDB_PUBLIC_BASE_URL and every CORS origin must use HTTPS. Origins cannot include credentials, query strings, fragments, or non-root paths.
• Leave FFDB_TRUSTED_PROXY_CIDRS empty for direct Axum access. Native installs trust loopback only; Docker installs use the deployment's explicit isolated subnet. Never use 0.0.0.0/0 or ::/0.
• FFDB_MASTER_KEY and FFDB_BACKUP_MASTER_KEY must each decode to exactly 32 bytes.
• FFDB_CURSOR_HMAC_KEY and FFDB_BOOTSTRAP_TOKEN must each contain at least 32 characters.
• The browser-facing FFDB_S3_PUBLIC_ENDPOINT must be public HTTPS and cannot resolve to private or local addresses.
• A private HTTPS FFDB_S3_ENDPOINT requires FFDB_S3_ALLOW_PRIVATE_NETWORK=true and remains bound to its exact hostname.
• SMTP is rejected in production. Resend credentials must remain server-side.
• Database, backup, and metrics roots must be specific paths, not /, empty paths, or paths containing parent traversal.

Client options

• baseUrl must use HTTP or HTTPS and cannot contain user information, a query, or a fragment.
• projectId identifies the project for SQL, auth, storage, and sync routes.
• developerKey enables trusted administration and must be omitted from browser and mobile applications.
• Provide fetch and a SessionStore implementation when the runtime does not expose browser defaults.
• BrowserSessionStore persists the end-user access/refresh pair in the Storage object you supply; sessionStorage limits persistence across browser restarts but does not defend against same-origin XSS.

import { BrowserSessionStore, FFDBClient } from "@ffdb/client";

const ffdb = new FFDBClient({
  baseUrl: "https://data.example.com",
  projectId: "019fc39c-ddbd-7d12-9849-e4ee35310132",
  sessionStore: new BrowserSessionStore(
    window.sessionStorage,
    "my-app.ffdb-session",
  ),
});

Choose the browser API origin

The packaged portal uses its current browser origin when VITE_FFDB_API_URL is absent, so http://127.0.0.1:5173/app/ calls the same installed gateway that served it. A separately built application may set VITE_FFDB_API_URL to an explicit FFDB origin.

Local acceptance does not depend on ffdb.forever-frameworks.com. A pre-deployment 403 from that public hostname describes the remote host only; verify the installed release through loopback until TLS and DNS are ready.

# Local acceptance build
VITE_FFDB_API_URL=http://127.0.0.1:5173

# Production build after TLS and DNS cutover
VITE_FFDB_API_URL=https://data.example.com

Configuration workflow

• 1. Generate independent secrets and record their rotation owners.
• 2. Fill every required packaged template value without changing reserved paths.
• 3. Run production configuration validation.
• 4. Start the service and verify readiness plus provider access.
• 5. Construct clients with only runtime-appropriate values.

Verify configuration

The server starts without placeholders, clients contain no operator secrets, and each provider is reached through its intended boundary.

Troubleshoot configuration

• Production validation reports a weak or missing value — replace it; never downgrade the environment mode.
• Browser assets contain a developer key — revoke it and rebuild from a clean configuration.

Continue from Configuration

• Install the selected server package.
• Review key rotation and production security.