Skip to content

Running on a VPS

Kunoru runs on a single server with Docker Compose. Everything is in the repository’s Deploy folder:

Service What it does
proxy Caddy: HTTPS with automatic Let’s Encrypt certificates for your domain, and the docs site at docs.{domain}
web The app, API, MCP server and live doc editing, on one port
worker Background jobs: file checks, emails, webhooks, Roblox publishing
migrate Runs database migrations once per deploy, before the app and worker start
postgres The database (Postgres 17), stored in DB_DIR on the server’s drive
clamav Virus scanning of uploads

Uploaded files live in FILES_DIR on the server’s own drive.

On a fresh Ubuntu or Debian server with Docker installed, and your domain’s A record (and docs. subdomain) pointing at it:

Terminal window
git clone <your repository> /srv/baseplate/app
cd /srv/baseplate/app
cp Deploy/.env.example Deploy/.env
nano Deploy/.env # fill in the required settings
Deploy/deploy.sh

deploy.sh builds the images, runs the migrations, starts everything and waits until https://{domain}/healthz answers. Caddy gets the certificates on the first request. Sign in with an address listed in PLATFORM_OWNER_EMAILS to become the platform owner.

To update later, run Deploy/deploy.sh again. It pulls, rebuilds, migrates and restarts. Each build is labelled with its git commit, which shows up in the logs and error reports.

Settings go in Deploy/.env (never commit it). Deploy/.env.example lists them all with comments. The important ones:

Variable What it is
DOMAIN, ACME_EMAIL Your public address, and where Let’s Encrypt writes about certificates
POSTGRES_PASSWORD Database password. Use hex (openssl rand -hex 32), since it goes into a URL
BETTER_AUTH_SECRET, ENCRYPTION_KEY Two different random strings of 32+ characters (openssl rand -base64 48). Keep ENCRYPTION_KEY safe: payout details and 2FA secrets can’t be read without it
PLATFORM_OWNER_EMAILS Who becomes platform owner on sign-in
FILES_DIR, DB_DIR Where files and the database live on the drive (default /srv/baseplate/files and /srv/baseplate/postgres)
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, MAIL_FROM Notification email through any SMTP mailbox, e.g. MXroute (port 465)
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_TAX Billing. Leave empty to keep the free beta
SENTRY_DSN Optional. Where errors are reported (see Monitoring)
DISCORD_*, GITHUB_* See the Discord and GitHub pages

The compose file sets the database address, storage folder, ClamAV address and the proxy settings itself. The deploy and backup scripts read Deploy/.env in bash too, so quote any value with spaces, < or >.

Live editing keeps open pages in the web process’s memory and writes them to Postgres a moment after people stop typing. Board updates reach every process through Postgres LISTEN/NOTIFY, but live doc editing doesn’t yet, so run one web process.

Browsers upload and download through short-lived signed links that the web process streams straight to and from disk, so a 5 GB file never sits in memory. Each studio’s storage limit comes from its plan.

Deploy/backup.sh backs up a database dump and all uploaded files into an encrypted restic repository on another provider, such as a Hetzner Storage Box (over SFTP) or Backblaze B2. restic deduplicates, so each night only sends what changed. It keeps 7 daily, 4 weekly and 6 monthly snapshots, and reads part of the backup back each night to check it.

Terminal window
apt install restic
# set RESTIC_REPOSITORY and RESTIC_PASSWORD in Deploy/.env, then once:
Deploy/backup.sh --init
# and nightly, with crontab -e:
30 3 * * * /srv/baseplate/app/Deploy/backup.sh >> /var/log/baseplate-backup.log 2>&1

Keep RESTIC_PASSWORD and ENCRYPTION_KEY somewhere off the server, such as a password manager. Without them the backups can’t be used.

Terminal window
set -a; . Deploy/.env; set +a
restic snapshots --tag baseplate # pick one
restic restore latest --tag baseplate --target /tmp/restore
docker compose -f Deploy/compose.production.yml stop web worker
docker compose -f Deploy/compose.production.yml exec -T postgres \
pg_restore -U baseplate -d baseplate --clean --if-exists < /tmp/restore/srv/baseplate/backups/baseplate.dump
rsync -a --delete /tmp/restore/srv/baseplate/files/ "$FILES_DIR"/
docker compose -f Deploy/compose.production.yml start web worker

Try a restore on a spare server now and then, so the first time isn’t an emergency.

  • Health check: https://{domain}/healthz answers 200 with {"ok":true,…} when the database answers and files can be stored, and 503 otherwise. Its jobs field turns false when background work has waited over five minutes (the worker is down or behind). Point an uptime monitor at it, such as Better Stack, UptimeRobot or Uptime Kuma. Docker also uses it to restart the app if it stops answering.
  • Errors: set SENTRY_DSN to a Sentry or self-hosted GlitchTip project. Server errors, browser errors and background jobs that fail for good are reported with the request id, the page path (never the query string) and the user’s id. No emails, cookies or request bodies are sent.
  • Logs: each line is one JSON object, for example {"level":"info","message":"request","method":"GET","path":"/kotzuki","status":200,"ms":42}. Read them with docker compose -f Deploy/compose.production.yml logs -f web worker. Every response carries an x-request-id header, and error pages show the first part of it, so a report from someone can be matched to its log lines. Set LOG_LEVEL=debug for more detail.

Billing switches on when STRIPE_SECRET_KEY is set. Then:

  1. In Stripe, create a product with a monthly price (and a yearly one if you offer it) for each paid plan, and paste each price id into Platform → Billing.
  2. Add a webhook pointing at https://your-domain/api/stripe/webhook with the events checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted and the invoice.* events. Put its signing secret in STRIPE_WEBHOOK_SECRET.
  3. Turn on the Customer Portal in Stripe’s settings, allowing card updates, invoice history and cancelling.

New studios then start with a trial. Studios already in the beta stay there until you press End beta in Platform → Billing.