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.
First deploy
Section titled “First deploy”On a fresh Ubuntu or Debian server with Docker installed, and your domain’s A record (and docs. subdomain) pointing at it:
git clone <your repository> /srv/baseplate/appcd /srv/baseplate/appcp Deploy/.env.example Deploy/.envnano Deploy/.env # fill in the required settingsDeploy/deploy.shdeploy.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
Section titled “Settings”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.
Files and backups
Section titled “Files and backups”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.
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>&1Keep RESTIC_PASSWORD and ENCRYPTION_KEY somewhere off the server, such as a password manager. Without them the backups can’t be used.
Restoring a backup
Section titled “Restoring a backup”set -a; . Deploy/.env; set +arestic snapshots --tag baseplate # pick onerestic restore latest --tag baseplate --target /tmp/restoredocker compose -f Deploy/compose.production.yml stop web workerdocker compose -f Deploy/compose.production.yml exec -T postgres \ pg_restore -U baseplate -d baseplate --clean --if-exists < /tmp/restore/srv/baseplate/backups/baseplate.dumprsync -a --delete /tmp/restore/srv/baseplate/files/ "$FILES_DIR"/docker compose -f Deploy/compose.production.yml start web workerTry a restore on a spare server now and then, so the first time isn’t an emergency.
Monitoring
Section titled “Monitoring”- Health check:
https://{domain}/healthzanswers200with{"ok":true,…}when the database answers and files can be stored, and503otherwise. Itsjobsfield turnsfalsewhen 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_DSNto 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 withdocker compose -f Deploy/compose.production.yml logs -f web worker. Every response carries anx-request-idheader, and error pages show the first part of it, so a report from someone can be matched to its log lines. SetLOG_LEVEL=debugfor more detail.
Billing
Section titled “Billing”Billing switches on when STRIPE_SECRET_KEY is set. Then:
- 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.
- Add a webhook pointing at
https://your-domain/api/stripe/webhookwith the eventscheckout.session.completed,customer.subscription.created,customer.subscription.updated,customer.subscription.deletedand theinvoice.*events. Put its signing secret inSTRIPE_WEBHOOK_SECRET. - 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.