How it fits together
Render builds the app from your Git repository and starts it on a fresh filesystem on every deploy. Anything the app writes outside a persistent disk is lost at the next deploy or restart. Carnival3 keeps three things that must survive:
- The database:
TURSO_DATABASE_URL=file:/var/data/local.dbputs it on the disk. - Media and site assets (
uploads/), themes added in Admin > Themes (uploaded-themes/) and logs (logs/): the start scriptscripts/render-start.shlinks these folders to the disk before starting the server. - The app secret, which signs sessions: set
APP_SECRETas an environment variable. Without it the app writes a random.app_secretfile, which a deploy deletes, signing everyone out.
cache/ stays off the disk: cached pages are cleared at every start anyway.
What you need
- The project in a GitHub, GitLab or Bitbucket repository, including
bun.lock,render.yamlandscripts/render-start.sh. - A paid instance. The smallest one (0.5 CPU, 512 MB) is enough for a typical site. Persistent disks are not available on the free plan.
- Optionally a domain name.
Limits of this setup
- One instance only. A service with a disk cannot scale to several instances. Carnival3 needs a single process anyway, because the cache index, the settings memo, the active-site cache and the rate limiter live in its memory.
- Short downtime on each deploy. With a disk attached, Render stops the old instance before starting the new one (no zero-downtime deploys). Expect a few seconds to a minute of errors during a deploy.
- The free plan loses data. It has no disk and spins down after 15 minutes without traffic (the next visit waits about a minute). It also blocks outgoing SMTP, so no email. Use it only for a throwaway preview: start command
bun server.ts, and expect the database and uploads to reset.
1. Create the service from the Blueprint
The repository contains a Blueprint, render.yaml, that describes the whole service:
services:
- type: web
name: carnival3
runtime: node # Render has no Bun runtime; Bun is installed from BUN_VERSION
plan: 0.5c-512mb # a paid instance: the free plan has no persistent disk
region: oregon
buildCommand: bun install --frozen-lockfile
startCommand: sh scripts/render-start.sh
healthCheckPath: /health
autoDeployTrigger: commit
disk:
name: data
mountPath: /var/data
sizeGB: 1
envVars:
- key: BUN_VERSION
value: 1.3.5
- key: APP_ENV
value: production
- key: APP_URL
sync: false
- key: APP_SECRET
generateValue: true
- key: TURSO_DATABASE_URL
value: file:/var/data/local.db
- key: DATA_DIR
value: /var/data
- key: CLIENT_IP_HEADER
value: True-Client-IP
- key: LOG_LEVEL
value: ERROR
- key: CACHE_ENABLED
value: "true"
- Change
name(it becomeshttps://<name>.onrender.com) andregion(oregon,ohio,virginia,frankfurtorsingapore; pick the one closest to your visitors), then commit and push. - In the Render Dashboard choose New > Blueprint, connect the repository and select the branch.
- Render asks for the values marked
sync: false. EnterAPP_URL, the public address withhttps://and no trailing slash, for examplehttps://carnival3.onrender.com. - Apply. Render creates the disk and the service, runs
bun install, then the start script.
If Render rejects the plan value, its instance names have changed: remove the line, deploy, and choose the instance type in the service's Settings.
Without the Blueprint
The same service can be created by hand with New > Web Service: language Node, build command bun install --frozen-lockfile, start command sh scripts/render-start.sh, a paid instance type, health check path /health, the environment variables below, and under Advanced > Disk a disk mounted at /var/data. For APP_SECRET, use Generate or paste the output of openssl rand -hex 32.
2. Environment variables
| Variable | Value | Why |
|---|---|---|
BUN_VERSION | 1.3.5 | The Bun version Render installs. Keep it equal to the version you develop and test with (bun --version). |
APP_ENV | production | No stack traces on error pages. |
APP_URL | https://… | Absolute links in emails (verification, password reset), the sitemap and robots.txt. |
APP_SECRET | generated | Signs sessions and tokens. Changing it signs everyone out. |
TURSO_DATABASE_URL | file:/var/data/local.db | The SQLite file on the disk. |
DATA_DIR | /var/data | Where the start script keeps uploads/, uploaded-themes/ and logs/. Must match the disk's mount path. |
CLIENT_IP_HEADER | True-Client-IP | The header with the visitor's real address (see below). |
LOG_LEVEL | ERROR | WARN or INFO for more detail. |
CACHE_ENABLED | true | Page cache. Admin > Settings > Cache overrides it once saved. |
Do not set PORT: Render provides it (10000) and the app listens on it on all interfaces. Leave TURSO_AUTH_TOKEN unset for a local database.
Visitor addresses: CLIENT_IP_HEADER
The rate limiter (sign-in, registration, password reset, contact form), the maintenance-mode IP allow list and the audit log use the visitor's IP address. Render's proxy adds the real address to the end of X-Forwarded-For and keeps whatever the visitor sent, so the first entry can be forged. Render also sends True-Client-IP, which visitors cannot set. With CLIENT_IP_HEADER=True-Client-IP, Carnival3 reads that header first and only falls back to X-Forwarded-For when it is missing.
Never put the database under uploads/: everything there is served publicly at /uploads/….
3. First start
No setup step is needed. On the first start the app creates the database, the starter site (theme starter, default and active) with its starter pages, and one administrator:
test@c3.com / 123456
- Wait until the deploy shows Live, open
https://<name>.onrender.com/adminand sign in (it takes you to/admin/login). - Immediately change the password (My Profile in the admin) and the email to your own address (Admin > Users). The default administrator is only created while there is no administrator at all, so renaming it does not bring
test@c3.comback on the next start. - Set up email in Admin > Settings > Email Service and send a test from the Test Email box below the form, and set the contact email of the active site in Admin > Sites.
- Visit
/health: it answers{"status":"ok", "db":"ok", …}(status, time, uptime and database only). Render uses it to decide whether a deploy succeeded; it answers 503 when the database cannot be read.
4. Custom domain
- In the service, Settings > Custom Domains > Add, enter the domain and create the DNS records Render shows (a CNAME to
<name>.onrender.com, or the A record for an apex domain). - Render issues the HTTPS certificate on its own once the DNS resolves.
- Change
APP_URLtohttps://yourdomain.com(Environment tab). Saving restarts the service.
5. Deploying changes
With autoDeployTrigger: commit, every push to the branch deploys: bun install, then a restart. Module schema changes are applied at startup and cached pages are cleared, so visitors see new templates right away. Remember the short downtime during each deploy, and run bun test before pushing.
Set autoDeployTrigger: off to deploy only with Manual Deploy in the Dashboard.
New modules come with a deploy, which restarts the service. Admin > Modules > Restart server also works on Render (detected from the RENDER variable): Render starts the service again after it exits. It is rarely needed there, as the code folders only change with a deploy.
Keep these in Git, not in the admin
Only the database, uploads/, uploaded-themes/ and logs/ are on the disk, so themes added, duplicated or edited in Admin > Themes survive deploys. These admin actions write into the code folders, which the next deploy replaces:
- widget type ZIP uploads (
widgets/<type>/); - new sites in Admin > Sites, which create
modules/site/<name>/init.ts.
Create these on your computer (bun run make:site, the widget folders), commit them and deploy. A site created in the admin on Render keeps its database row but loses its folder at the next deploy; it still works with its theme as long as the theme is in Git.
6. Backups
- Disk snapshots: Render takes a snapshot of the disk every day and keeps it for at least 7 days. Restore one from the service's Disks page. A restore replaces the whole disk (database and uploads) and restarts the service.
- Your own copies: open the service's Shell tab (or SSH) and run
It writes a consistent copy (bun run cli db:backupVACUUM INTO, safe while the app runs) to/var/data/backups/local-<date>.db. Copy it, and/var/data/uploadsif needed, to your computer withscpover Render SSH or withmagic-wormhole; see Render's disk documentation, "Transferring files". Delete old copies from/var/data/backupsso the disk does not fill up. - Never copy
local.dbwithcpwhile the app is running: the copy may be inconsistent. Usedb:backup.
To move an existing database to Render, copy it (made with db:backup) to /var/data/import.db, then set TURSO_DATABASE_URL=file:/var/data/import.db in the Environment tab; saving restarts the service on that file. Never overwrite the database file the app has open.
7. Logs and monitoring
- The Logs tab in Render shows the server output (startup messages, errors).
- Admin > Application Logs reads
logs/, which is on the disk and survives deploys. - Render restarts the service when
/healthkeeps failing. - Admin > System > Server Status (optional Server Health module) shows memory against the instance's limit (read from the container), CPU, response times, errors, database delay and the space left on the disk, with graphs for the last hour, day and week. Render's Metrics tab shows the same container from the outside (CPU, memory, bandwidth).
- Error alerts: once email works, administrators get an email when errors pile up (default 10 errors in 5 minutes, then quiet for an hour). Recipients and limits: Admin > Settings > Error Alerts. Render can also email you about failed deploys (its notification settings).
8. Email
Email works on paid instances with any SMTP provider (port 587 with STARTTLS, or 465 with "Secure"). Render's free plan blocks outgoing SMTP ports, so registration emails, password resets and the contact form cannot send there.
9. Disk size
The database is usually a few MB; uploads (with their thumbnails) take most of the space. Start with 1 GB. A disk can be made larger later in the Dashboard (not smaller); watch its usage on the Disks page.
Static hosting for the public site
A site can also be exported as plain HTML, CSS and JS (Admin > Sites, the download button) and published on Render as a free Static Site. The web service then serves only the admin and the contact form. See How to create a site, "Export as a Static Site".
Moving to Turso later
The code does not change. Create a Turso database, import local.db into it (for example turso db create my-db --from-file local.db, using a copy made with db:backup), set TURSO_DATABASE_URL=libsql://… and TURSO_AUTH_TOKEN, and deploy. Keep the disk for uploads/ and logs/.
Checklist
- Paid instance with a disk mounted at
/var/data;DATA_DIRmatches it. TURSO_DATABASE_URL=file:/var/data/local.dbandAPP_SECRETset.APP_ENV=production,APP_URLset to the public HTTPS address.CLIENT_IP_HEADER=True-Client-IP.BUN_VERSIONequal to your local Bun version.- Default administrator's password and email changed.
- Email set up and tested; the active site's contact email set; error alert recipients checked (Settings > Error Alerts).
- Themes, widget types and site folders committed to Git.
- Staging services: Allow search engines turned off (Settings > SEO & Analytics).
- A backup routine: daily snapshots plus your own
db:backupcopies.
For a VPS with PM2 or systemd instead, see the Deployment Guide.