Operator docs

Railway deployment and migrations

Use this when explaining how partners.headlessdomains.com deploys safely after database changes.

Startup Order

1. Railway runs the service start commandrailway.json sets deploy.startCommand to ./start.sh.

2. Flask app target is setstart.sh exports FLASK_APP=run.py.

3. Migrations run firstflask db upgrade applies pending Flask-Migrate/Alembic migrations before web traffic is served.

4. Gunicorn starts after migrationsgunicorn run:app starts only after migration success because start.sh uses set -euo pipefail.

Railway runs ./start.sh, which exports FLASK_APP=run.py, applies Flask-Migrate/Alembic migrations with flask db upgrade, then starts Gunicorn.

Railway start command railway.json deploy.startCommand is ./start.sh. Ready

Flask app target start.sh exports FLASK_APP=run.py before migrations. Ready

Migration step start.sh runs flask db upgrade before the web server starts. Ready

Web server step start.sh starts gunicorn run:app after migrations. Ready

Railway deploy
  -> railway.json startCommand: ./start.sh
  -> start.sh exports FLASK_APP=run.py
  -> flask db upgrade
  -> gunicorn run:app

For model or migration changes, run PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest and a fresh database migration check before pushing.