How to run an app that keeps its own SQLite database
Run it as one container with a persistent volume mounted at the directory the app documents for its storage, supply its secret key from outside the image, and complete the app's first-run setup once. An app like Campfire — a self-hosted team chat — ships its own web server, background worker, Redis and database, so the host's job is to give it one writable directory that outlives the container and the configuration it cannot generate itself.
Campfire is the worked example; the same shape fits any app whose documentation says its database and uploads live in one directory. Cloudish is one host that exposes these pieces; it appears here as an example, not a recommendation.
1. Run one container, not a replica set
SQLite is a file, so every copy of the app that can write it
must sit on the same volume, and a block volume attaches to one
container. Cloudish's API reference says
volumeSizeGb must be 1, 5 or 20, that
volumeMountPath defaults to /data, and that "A
volume can only attach to one container, so an app with one can't run
replicas" (Cloudish,
skill.md, checked 2026-11-12).
That matches what Campfire asks for: "Campfire keeps all of its
storage - the database and uploaded file attachments - inside the path
/rails/storage" (Campfire,
Self-hosting Campfire, checked 2026-11-12). Mount the volume at that
path, not at the host's default: a volume at /data leaves
the database inside the container and loses it on the next deploy.
2. Keep the instance's secrets out of the image
Campfire needs a SECRET_KEY_BASE and a VAPID
private/public key pair, and its docs say to reuse the same values
across restarts and upgrades (Campfire,
Self-hosting Campfire, checked 2026-11-12). Generate them once,
store them in the host's secret store,
and let them reach the container as environment variables.
Cloudish stores secrets encrypted at rest and merges them into the
container environment; saving or deleting one restarts a running app,
and an idle app receives the values when it next starts (Cloudish, skill.md,
checked 2026-11-12).
A SECRET_KEY_BASE that changes invalidates signed
session cookies, so a redeploy that regenerates it signs every user out.
Keep it stable.
3. Pin the process counts to the container's size
An image that sizes its worker pool from the host's CPU count
can start far more processes than its container's CPU limit, and the
memory limit is what gets hit. Campfire's Puma config uses
workers ENV.fetch("WEB_CONCURRENCY") { worker_count }, and
its job-pool config is
default: <%= (Concurrent.processor_count * 0.5).ceil %>
(config/puma.rb,
config/resque-pool.yml,
checked 2026-11-12). Set the web worker count explicitly, and the
job-pool size too when the image reads one.
For Campfire the job pool comes from a YAML file rather than an
environment variable, so the explicit value has to be in the image: a
one-line wrapper Dockerfile that copies a default: 1 config
over the stock one is enough. The web server is set with
WEB_CONCURRENCY=1.
4. Decide where TLS terminates
Either the container terminates TLS (Campfire:
TLS_DOMAIN) or a proxy in front does; Campfire's docs say
to set DISABLE_SSL=true in the second case and publish port
80 (Campfire,
Self-hosting Campfire, checked 2026-11-12). Whichever you pick,
check the result: a redirect to the public URL should be
https, and the session cookie should carry
Secure.
Port numbers matter as much as TLS. Campfire's image runs Thruster, a
proxy that listens on port 80 by default and forwards to Puma on
TARGET_PORT, default 3000 (Thruster,
README, checked 2026-11-12). Tell the host port 80, not the port
Puma listens on inside the container.
5. Finish the first-run setup once
Many self-hosted apps create the first admin account through a web form, not an environment variable. Campfire's docs say that when you start it for the first time, "you'll be guided through creating an admin account" (Campfire, Self-hosting Campfire, checked 2026-11-12). Open the site, complete the form, and note the email shown on the sign-in page: it is the admin's address, shown as the contact for anyone who forgets a password.
If a script or agent has to complete it, the form may not carry a
CSRF token. Rails 8.2's :header_only strategy "Uses the
Sec-Fetch-Site header sent by modern browsers" and "does
not require authenticity tokens"; requests without a valid
Sec-Fetch-Site header are rejected (Rails,
request_forgery_protection.rb, checked 2026-11-12). Send the POST
with Sec-Fetch-Site: same-origin and an Origin
equal to the site's base URL, and it is treated like a browser form
submit.
6. Check the app, not the deploy response
Wait for the build, then read the logs: the web server should say it is listening, and the job worker should say it started. The health endpoint answers when the app is up. Then sign in with the admin account: that exercises the database write path and the session cookie at once. How to tell whether a deploy actually worked gives the general checklist.
Related pages
- Where an AI-built app keeps its data
- How to tell whether a deploy actually worked
- The cloud, for AI apps
- How to shrink a container image
See also
Glossary terms used on this page: Agent, API, Container, Deploy, Dockerfile, Environment variable, Host, Logs, Secret, Token.
Sources
All checked on 2026-11-12.
- Campfire, Self-hosting Campfire
- Campfire, config/puma.rb; config/resque-pool.yml
- Thruster, README
- Rails, Action Controller Request Forgery Protection
- Cloudish, skill.md
First version written with AI assistance and checked against the sources on 2026-11-12. Found a mistake? Fix it or open an issue. Text licensed under CC BY 4.0.