Deployment Guide

Deploy your ScribeEngine app to production.

Production Checklist

Before deploying:

  • Change secret_key in scribe.json to a random value
  • Decide how migrations are applied (see Migrations in Production)
  • Enable HTTPS (SSL/TLS)
  • Set debug=False in Flask
  • Use environment variables for secrets
  • Set up monitoring/logging
  • Configure backups

Using Production Server

ScribeEngine includes Waitress (production WSGI server):

scribe serve --host 0.0.0.0 --port 8000 --threads 8

Options:

  • --host: IP address (0.0.0.0 = all interfaces)
  • --port: Port number
  • --threads: Worker threads
  • --migrate / --no-migrate: Override each connection's auto_migrate for this run

Migrations in Production

By default, scribe serve applies pending migrations at startup for connections with "auto_migrate": true (including default when the key is missing). For production, it is usually better to apply them as an explicit deploy step:

  1. Set "auto_migrate": false on the connection in scribe.json.
  2. In your deploy script, run migrations before restarting the server:
scribe db status    # optional: review what will run
scribe db migrate
sudo systemctl restart myapp

With auto_migrate off, scribe serve still starts normally and prints a warning if migrations are pending.

Standalone Executables (scribe-build)

scribe-build compiles a project into a single executable you can hand to someone without shipping your source code, a Python install, or scribe itself. It's installed alongside scribe by install.sh.

scribe-build build                    # build ./ into ./dist/<dirname>
scribe-build build --name mytool      # custom executable name
scribe-build build --output ~/builds  # custom output directory

Routes and lib/ helpers are precompiled to bytecode. static/, migrations/, base.stpl, and a copy of scribe.json with secrets stripped are bundled in.

Requirements: the project needs its own venv (.venv, venv, or env, or point --venv at one). scribe-build freezes the app through that venv's Python with PyInstaller, and installs anything missing (PyInstaller, Flask, and Scribe's other runtime dependencies) into it before building:

python -m venv .venv
.venv/bin/pip install -r requirements.txt    # your app's own dependencies, if any
scribe-build build

Runtime configuration: SECRET_KEY and database passwords are never embedded in the executable. Set them when you run it:

SECRET_KEY=... PORT=8080 ./dist/myapp
  • HOST / PORT: bind address and port (default 0.0.0.0:8000)
  • SECRET_KEY: session signing key
  • SCRIBE_DB_<NAME>_PASSWORD: password for the <name> connection in scribe.json, e.g. SCRIBE_DB_DEFAULT_PASSWORD

Run scribe-build build --help for every option.

PostgreSQL Configuration

Edit scribe.json:

{
  "databases": {
    "default": {
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "user": "myapp_user",
      "password": "USE_ENV_VARIABLE",
      "database": "myapp_db",
      "migrations": "migrations",
      "auto_migrate": false
    }
  },
  "SECRET_KEY": "USE_ENV_VARIABLE"
}

Don't commit secrets! Use environment variables.

Nginx Reverse Proxy

server {
    listen 80;
    server_name myapp.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Systemd Service

Create /etc/systemd/system/myapp.service:

[Unit]
Description=MyApp ScribeEngine
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/usr/local/bin/scribe serve --host 127.0.0.1 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp

See other guides for development workflows.