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.db puts it on the disk.
  • Media and site assets (uploads/), themes added in Admin > Themes (uploaded-themes/) and logs (logs/): the start script scripts/render-start.sh links these folders to the disk before starting the server.
  • The app secret, which signs sessions: set APP_SECRET as an environment variable. Without it the app writes a random .app_secret file, 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.yaml and scripts/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"
  1. Change name (it becomes https://<name>.onrender.com) and region (oregon, ohio, virginia, frankfurt or singapore; pick the one closest to your visitors), then commit and push.
  2. In the Render Dashboard choose New > Blueprint, connect the repository and select the branch.
  3. Render asks for the values marked sync: false. Enter APP_URL, the public address with https:// and no trailing slash, for example https://carnival3.onrender.com.
  4. 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

VariableValueWhy
BUN_VERSION1.3.5The Bun version Render installs. Keep it equal to the version you develop and test with (bun --version).
APP_ENVproductionNo stack traces on error pages.
APP_URLhttps://…Absolute links in emails (verification, password reset), the sitemap and robots.txt.
APP_SECRETgeneratedSigns sessions and tokens. Changing it signs everyone out.
TURSO_DATABASE_URLfile:/var/data/local.dbThe SQLite file on the disk.
DATA_DIR/var/dataWhere the start script keeps uploads/, uploaded-themes/ and logs/. Must match the disk's mount path.
CLIENT_IP_HEADERTrue-Client-IPThe header with the visitor's real address (see below).
LOG_LEVELERRORWARN or INFO for more detail.
CACHE_ENABLEDtruePage 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
  1. Wait until the deploy shows Live, open https://<name>.onrender.com/admin and sign in (it takes you to /admin/login).
  2. 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.com back on the next start.
  3. 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.
  4. 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

  1. 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).
  2. Render issues the HTTPS certificate on its own once the DNS resolves.
  3. Change APP_URL to https://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
    bun run cli db:backup
    It writes a consistent copy (VACUUM INTO, safe while the app runs) to /var/data/backups/local-<date>.db. Copy it, and /var/data/uploads if needed, to your computer with scp over Render SSH or with magic-wormhole; see Render's disk documentation, "Transferring files". Delete old copies from /var/data/backups so the disk does not fill up.
  • Never copy local.db with cp while the app is running: the copy may be inconsistent. Use db: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 /health keeps 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_DIR matches it.
  • TURSO_DATABASE_URL=file:/var/data/local.db and APP_SECRET set.
  • APP_ENV=production, APP_URL set to the public HTTPS address.
  • CLIENT_IP_HEADER=True-Client-IP.
  • BUN_VERSION equal 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:backup copies.

For a VPS with PM2 or systemd instead, see the Deployment Guide.