state-server's persistence is feature-flagged between MongoDB and FoundationDB. The code default is MongoDB; production overrides it to FoundationDB.
| Source | Evidence | Effective mode |
|---|---|---|
Code default (config/config.go:258) |
FDB_ENABLED default false. FDB_DUAL_WRITE default false. FDB_READ_PREFERENCE default "fdb". |
MongoDB |
Production deployment (avvy/argocd/state-server-all/base/deployment.yaml) |
Init container waits for fdb-cluster-file; runtime mounts fdb-cluster-file volume; state-server-config Kubernetes Secret presumably sets FDB_ENABLED=true. |
FoundationDB |
Migration guide (state-server/docs/DEPLOYMENT_GUIDE_FDB.md) |
Explicitly titled "FoundationDB State Server - Comprehensive Deployment Guide" with rollback procedures and a "Migration from MongoDB" section. | FDB is the migration target. |
Net: production runs on FoundationDB, but the code remains capable of running against MongoDB (used in local dev via external/mongo/docker-compose.yaml). FDB_DUAL_WRITE exists for a phased cut-over and is off by default.
Deployed via the FoundationDB Operator from avvy/argocd/foundationdb/base/fdb.yaml, with per-environment overlays at foundationdb/overlays/{avvy-dev, avvy-prod, avvy-test}/patch-cluster.yaml. Operator runs in fdb-system namespace.
The cluster file produced by the operator is mounted into the state-server pod and into each FDB-aware client via a shared ConfigMap / Secret.
| Env var | Default | Purpose |
|---|---|---|
FDB_ENABLED |
false |
Master switch. Production sets true. |
FDB_CLUSTER_FILE |
fdb.cluster |
Path to operator-provided cluster file. |
FDB_DUAL_WRITE |
false |
Write to MongoDB AND FDB during migration. |
FDB_READ_PREFERENCE |
"fdb" |
Read source when both stores hold data. |
FDB_CHANGE_POLL_INTERVAL |
50ms |
Change-stream polling. |
FDB_CHANGE_BATCH_SIZE |
1000 |
Change-stream batch size. |
FDB_CHANGE_MAX_SUBSCRIBERS |
10000 |
Subscriber cap. |
FDB_CHANGE_SUBSCRIBER_BUFFER |
100 |
Per-subscriber buffer. |
Source: state-server/config/config.go lines 252–283.
DEPLOYMENT_GUIDE_FDB.md documents three deployment shapes:
double redundancy, 1-node fault tolerance.Production overlay in ArgoCD targets a multi-pod cluster (see foundationdb/overlays/avvy-prod/patch-cluster.yaml).
Internal-only: 4500 (FDB client) and 4501–4510 (cluster comms).
state-server retains MongoDB code paths. Local development bootstraps a single-member replica set via state-server/external/mongo/docker-compose.yaml:
cd external/mongo
docker-compose up -d
# connection: mongodb://localhost:27017/?directConnection=true&replicaSet=rs0
Production does not deploy MongoDB — the ArgoCD repo has no MongoDB manifests. MongoDB is therefore retained as a fallback / dev mode, not as a production substrate.
avvy-worker writes preview images, processed CBOR, canonical GLBs, and projection artifacts to S3. Production target is Hetzner Object Storage:
S3_ENDPOINT=https://fsn1.your-objectstorage.com
S3_BUCKET=avvyland
S3_REGION=fsn1
S3_FORCE_PATH_STYLE=true
Credentials live in the avvy-worker-secrets Kubernetes Secret. AWS SDK v2 with path-style addressing.
Deployed via avvy/argocd/common/redis-{deployment,config,pvc,service}.yaml. In-cluster service name: redis:6379. Serves both as state-server's L2 cache and as the asynq task queue for avvy-worker.
DEPLOYMENT_GUIDE_FDB.md §9 covers FDB backup via fdbbackup to S3-compatible storage with fdbrestore for recovery. Schedule as systemd timers; verify restores periodically. No mirrored backup automation for MongoDB in current production manifests (because MongoDB is not the production substrate).
Deployment for the surrounding topology.
Redis task queue for the queue side.
state-server architecture.
Deployed services.
state-server/config/config.go (lines 252–283), state-server/docs/DEPLOYMENT_GUIDE_FDB.md, state-server/external/mongo/docker-compose.yaml, avvy/argocd/foundationdb/base/fdb.yaml + overlays, avvy/argocd/state-server-all/base/deployment.yaml, avvy/argocd/common/redis-*.yaml, avvy/argocd/avvy-worker/deployment.yaml (S3 env vars).