System requirements and topology
Facet is one backend binary, one frontend server, and two state stores. The backend holds every durable fact in PostgreSQL. Redis is the reaction bus. This page lists what a host needs and how the pieces connect, so you can size a deployment before you run it.
When to use this
Section titled “When to use this”Use this page when:
- You plan a host or a container stack for Facet.
- You decide between one database and a routed cluster.
- You check a machine against the requirements.
Requirements
Section titled “Requirements”| Component | Requirement | Notes |
|---|---|---|
| PostgreSQL | 14 or newer | The ulid() function needs PostgreSQL 14. One instance is enough for most installs. |
| Redis | Required | The event bus, sessions, OAuth codes, and rate limits use it. The release stack runs the redis:7 image. |
| Config file | config.{APP_ENV}.yml |
The boot fails without it. See Configuration files. |
| Backend binary | Release image, or make build_release |
Migrations, Lua event scripts, and the seed corpus ride inside the binary. |
| Docker with Compose | For the container path | The release stack is five services. See Deploying with containers. |
Topology
Section titled “Topology”The container stack runs five services:
| Service | Image | Faces the network? |
|---|---|---|
postgres |
pgvector/pgvector:0.8.0-pg17 |
No |
redis |
redis:7 |
No |
backend |
ghcr.io/wearefacet/facet |
No — the edge routes to it |
frontend |
ghcr.io/wearefacet/facet-frontend |
No — the edge routes to it |
caddy |
caddy:2 |
Yes — it publishes the TLS port |
The backend image runs as uid 10001. The frontend image runs as node.
A source deployment replaces the two application images with
make build_release and the SvelteKit dev or build server — see
Install for development.
Database topology
Section titled “Database topology”By default the backend opens one pool from DATABASE_URL. Every read and
every write shares that pool. Most installs stop here.
A larger install can split load with the optional database.cluster route
table. Each entry names one physical database and the resources it serves:
-
A resource is a domain id, a
$-prefixed subsystem tag, or*. -
Exactly one entry carries
*. It serves the control plane and everything unrouted. -
A specific resource appears in one entry only.
-
An entry can carry an optional read-only
replicapool. Every read-only pool runsSET default_transaction_read_only = on, so a mislabelled write fails loud. -
Entries that share one URL keep separate pools. This gives pool isolation without a second database.
database.statement_timeout_msapplies to every pooled connection of the server process. CLI entry points keep no timeout, so long DDL cannot be cancelled.
- Provision the state stores. Install PostgreSQL 14 or newer and Redis. Create one empty database for the first deploy.
- Put the config file in place. Set
event.urlto the Redis address andDATABASE_URLin the environment. See Configuration files. - Choose the database topology. Start with the single
DATABASE_URLpool. Add the route table when one pool no longer fits the load. - Run the stack. Use the container path for production — Deploying with containers — or build from source. The copy-paste walkthrough is Deploy to production.
Example
Section titled “Example”A cluster route table with one main database and one small bulk pool. Both entries share the same URL, so the bulk pool is pool isolation only:
database: statement_timeout_ms: 5000 cluster: databases: main: url: !env DATABASE_URL max_pool_size: 20 resources: ["*"] bulk_pool: url: !env DATABASE_URL max_pool_size: 8 resources: ["$bulk"]Troubleshooting
Section titled “Troubleshooting”The boot fails and names the config path.
The file does not exist at the resolved location. The boot never falls back to another environment’s file.
The boot fails with Missing required config key 'artifact_base_url'.
Add the required top-level keys. See Configuration files.
PostgreSQL raises an error inside ulid().
The server is older than PostgreSQL 14. Upgrade the server.
The boot fails with Missing 'event' key in config.
Add the event: section with the Redis URL. Redis is a required dependency.
Checkouts wait under load.
Watch the facet_db_checkout_total{database, role} metric and tune
max_pool_size per entry. A nested write inside a read scope holds two
connections for its duration.
Related
Section titled “Related”- Deploying with containers — the images and the TLS edge.
- Deploy to production — the copy-paste walkthrough.
- Configuration files — every key the config file takes.
- Database migrations — how the schema reaches the database.
- The big picture — the concepts behind the services.
- Internals on GitHub: container-images.md, first-deployment.md, config.md.