Simple Worship Presenter

Self-hosting

Run it on your own server.

Self-hosting is a first-class option, not a downgrade. There is no licence key, no subscription and no call home to us. A self-hosted instance performs every core presentation function on its own.

Requirements

Install

# 1. Get the code git clone https://github.com/alexanderwasson/simple-worship-presenter cd simple-worship-presenter # 2. Install dependencies exactly as locked npm ci # 3. Configure cp .env.example .env # edit SESSION_SECRET and DATA_DIR # 4. Run npm start

Environment variables

VariableDefaultDescription
PORT3000HTTP port for the application.
DATA_DIR./dataPersistent data root. Keep this outside the release directory so updates never overwrite user data.
SESSION_SECRET—Required in production. Long random string used to sign session tokens.
NODE_ENVdevelopmentSet to production to require HTTPS cookies and reject default secrets.
TRUST_PROXY0Set 1 behind CloudPanel/nginx so client IPs and secure cookies behave correctly.
INSTANCE_NAMESimple Worship PresenterName shown in the interface and health output.
PUBLIC_URL—Public base URL of the instance, if any.
DEFAULT_QUOTA_BYTES262144000Storage quota for new accounts (250 MB by default).
MAX_UPLOAD_BYTES262144000Maximum single upload size.
ALLOW_REGISTRATION1Set to 0 to close public registration on your instance.
LOG_LEVELinfodebug, info, warn or error.
RATE_LIMIT_MAX_AUTH10Sign-in attempts per minute per IP address.

First run

  1. Open the site in a browser.
  2. You will be asked to create the administrator account. This is only offered while the instance has no users.
  3. Sign in, then add accounts for your team, or let them self-register.
The administrator account is a normal account with one extra ability: changing the instance default storage quota in the API. All accounts are isolated from each other at the data layer.

Deploying with CloudPanel

  1. Create a Node.js App site and select Node 18+.
  2. Set the application root to the project folder and the startup file to server.js.
  3. Run npm ci in the application directory.
  4. Set PORT to the port CloudPanel assigns.
  5. Set DATA_DIR to a persistent path outside the release, for example /home/cloudpanel/htdocs/simple-worship-data.
  6. Set a long random SESSION_SECRET and TRUST_PROXY=1.
  7. Enable SSL in CloudPanel for your domain.

Deploying with Docker

# build and start docker compose up -d --build # the data volume persists across upgrades docker compose down && docker compose up -d --build

The included docker-compose.yml mounts a named volume at the data directory and exposes a health check at /api/health.

Upgrades

  1. Back up DATA_DIR.
  2. Fetch the new release.
  3. Run npm ci.
  4. Restart the process.

Database schema changes run automatically as numbered migrations on startup. Migrations are additive and never delete existing user data. If a data file cannot be read, the instance preserves a copy named *.corrupt-<timestamp> rather than overwriting it.

Backup and restore

# back up everything tar -czf swp-backup-$(date +%F).tar.gz "$DATA_DIR" # restore tar -xzf swp-backup-YYYY-MM-DD.tar.gz

Stopping the process before copying gives the most consistent snapshot, because the database is a single JSON document rewritten atomically on save.

Health checks

GET /api/health returns the instance name, version, schema version and uptime. Use it for load balancer and monitoring checks.

Browser display limitations

Browser applications cannot force a specific physical monitor on every operating system. The supported workflow is to open the audience display window and drag it to the projector, then press F for fullscreen. Windows, macOS and Linux may each handle this slightly differently.

Troubleshooting