Upgrading

Upgrades replace the code and keep your data and configuration. Database migrations are applied automatically when the new version starts, so there is no separate migration step.

How migrations work#

• Migrations are append-only and ship inside the kit. On start, ATS records which ones have run in a _migrations table and applies only the missing ones, in order.
• Each migration and its bookkeeping row are applied in one batch, so a failure leaves no half-applied schema. If two instances race, the second sees the work already done.
• Node.js / Docker: they run at process start, before the port opens. If one fails, the process exits with the error.
• Cloudflare: they run on the first request of each Worker isolate.
• There are no down-migrations. To go back to an older version after a newer one has started, restore your backup.

Before every upgrade#

1. Back up

   Self-hosted: snapshot ats.db with SQLite's .backup and copy files/ (see Docker or Node.js). Cloudflare: export D1 (npx wrangler d1 export ats --remote --output ats-backup.sql).

2. Download and verify the new kit
   Terminal

   curl -LO https://ats.goosenotes.dev/downloads/0.1.0/ats-0.1.0.tar.gz
   curl -LO https://ats.goosenotes.dev/downloads/0.1.0/SHA256SUMS
   grep ' ats-0.1.0.tar.gz$' SHA256SUMS | shasum -a 256 -c
   tar -xzf ats-0.1.0.tar.gz

3. Read the new kit's .env.example or wrangler.toml

   Compare them with what you run, in case a release adds a setting you want.

Docker#

1. Build the new image from the new kit
   Terminal

   cd ats-0.1.0
   docker build -f apps/node/Dockerfile -t ats:0.1.0 -t ats:latest .

2. Recreate the container
   Terminal

   cd ~/ats-deploy
   docker compose up -d
   docker compose logs -f ats      # watch it start and apply migrations

   The ats-data volume, your .env and Caddyfile are untouched. To roll back, retag the previous image as ats:latest and restore the backup taken before the upgrade.

Node.js#

1. Unpack next to the current version and install
   Terminal

   sudo tar -xzf ats-0.1.0.tar.gz -C /opt/ats
   cd /opt/ats/ats-0.1.0
   sudo npm ci --omit=dev

2. Switch over and restart
   Terminal

   sudo ln -sfn /opt/ats/ats-0.1.0 /opt/ats/current
   sudo systemctl restart ats
   journalctl -u ats -f

   /etc/ats/ats.env and /var/lib/ats stay where they are. The old folder remains in /opt/ats; to roll back, point current at it again and restore your backup.

Cloudflare#

1. Carry over your Wrangler configuration

   Copy your database_id, routes and [vars] from the old apps/cloudflare/wrangler.toml into the new one (or copy the old file over, then re-check it against the new one). Secrets live in Cloudflare and carry over.

2. Install and deploy
   Terminal

   cd ats-0.1.0
   npm ci
   npm run deploy -w @ats/cloudflare

   Migrations run on the first request to each new isolate. Keep the D1 export from before the upgrade until you are happy with the new version.

After upgrading#

• Check /ats/api/health and sign in.
• Send a test submission with the curl recipe if the release touched intake.