Profile A — single VPS (the default)
docker compose up -d: app + Postgres, local file storage on the app_data
volume, in-memory rate limits, Caddy in front for TLS
(reverse-proxy.md). Serves teams to small companies; a
bigger machine buys roughly 10×. This is the shape the install scripts and
backup scripts assume.
Profile B — horizontal / cloud (reference)
The same image, N autoscaling replicas (e.g. Cloud Run), with the state moved to managed services:
Profile B requires shared storage.
STORAGE_DRIVER=local is
single-replica only: each replica has a private disk, so a blob uploaded
through one replica does not exist on another. A replica that cannot reach a
blob answers a clean 404 not_found on the content route — that is a safety
net against silent corruption, not a supported mode of operation. Any
multi-replica deployment must set STORAGE_DRIVER=s3 (S3, MinIO, R2).
Requirements that make B safe are already Slideless invariants:
AUTO_MIGRATE under an advisory lock means one replica migrates while
others wait; pg-boss’s own install DDL (schema + queue partitions) is
serialized the same way under a second advisory lock (key 7432004,
jobs/pgboss.ts), so concurrent fresh-DB boots of all/worker replicas
do not deadlock; graceful drain means rolling deploys drop nothing (proven:
a SIGTERM mid-download lets the transfer finish); SERVICE_ROLE=api runs no
job supervision (note: it still applies the app migrations unless you set
AUTO_MIGRATE=false on the api pool — only the pg-boss DDL is skipped).
These claims are not just documented — they are exercised as a real
multi-replica stack by the scale drill (scripts/scale-drill.sh, run in CI
on every push to prod or dev and on every pull request): the migration-lock race, cross-replica sessions and API
keys, Redis-shared rate limits (with the in-memory contrast), and the
api/worker split. See scaling.md, including its findings on
first-boot ordering (a fresh database needs one all/worker boot before
api-only replicas can start).
Limiting workspace creation
Setup creates the instance’s first workspace. After that, any signed-in member who is not a guest can create another one from the dashboard and owns it (Workspaces). One variable bounds that:
Workspaces are isolated from each other: the owner of one reads nothing of another, and that
includes you as the owner of the first. What you keep as the operator is the instance itself: the
database, the backups, and break-glass recovery, which can make a
superadmin an owner of any workspace and says so in that workspace’s audit log. Once the instance
holds more than one workspace, a break-glass ownership claim has to name its workspace.
One consequence to know before you leave creation open: an account is one person across the whole
instance, so once a member also belongs to another workspace, an owner can no longer generate a
password-reset or change-email link for them (
403 cross_workspace_target), nor delete their
account (409 member_of_other_workspaces); the owner deactivates the membership instead. On an
instance with no email delivery, the owner’s reset link is the only way back in for a member who
forgot their password, and such a member no longer has it: configure an email driver so people can
reset their own password, or keep creation closed.
Set MAX_WORKSPACES_PER_USER=0 on an instance that should stay a single team’s. Workspaces that
already exist are unaffected by a lower value; only new creations are refused. The API quota is per
credential, not per workspace, so more workspaces do not raise it. Storage has no per-workspace
ceiling: size the volume for the instance as a whole.
Sizing storage for form uploads
Deck content is written by people with an account. Form uploads are the one thing anonymous share-link visitors write to storage: a deck form can carry a file field, and every respondent on a link with uploads on can add files to it (Forms). They land in the same storage as everything else (theapp_data volume with STORAGE_DRIVER=local, the
bucket with s3), under their own forms/ prefix, and three variables bound
them:
The worst case on disk is the number of decks that have a form with a file
field and a live link with uploads on, times
FORMS_MAX_UPLOADS_MB_PER_DECK: at the defaults, 5 GB per such deck. Nothing
caps the sum across decks, so either size the volume for that, lower the
per-deck total, or set FORMS_MAX_UPLOAD_MB=0 on an instance that should
never take files from the public. A deck that reaches its total refuses new
uploads (403 uploads_full) and keeps serving; nothing else on the instance
is affected. Deleting responses frees their space at once; deleting a deck
frees the space of its uploaded files at the nightly purge, a day after the
delete.
An upload in flight is first written to $DATA_DIR/tmp, then copied to
storage, so with s3 the local volume still needs room for the uploads
being received at one moment. Files that were uploaded and never submitted
are removed by a nightly job once they are 24 hours old. It runs on
the replicas that run jobs (SERVICE_ROLE=all or worker).
Connection pooling: the app’s pg.Pool ships conservative defaults (max 10
connections per replica, statement_timeout 30 s,
idle_in_transaction_session_timeout 30 s), so N replicas hold at most
10·N connections; size Postgres max_connections or the pooler
accordingly. Behind PgBouncer in transaction mode the two timeouts do
not stick: they are session-level settings, and transaction pooling hands
each transaction a different server session. Set them server-side instead
(ALTER DATABASE slideless SET statement_timeout = '30s', same for
idle_in_transaction_session_timeout) or run the pooler in session mode.
Kubernetes is an ops preference some enterprises impose, never a scale
requirement — the image runs unchanged; a Helm chart is a later add-on.