Gooseplicant

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, Gooseplicant 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.

From 0.2 to 0.3#

0.3 adds an optional intake-only port so the app and the data can stay on your network (Public intake, private app) and gives Gosling a new mark: a goose peeking out of an open folder. The upgrade follows the usual steps below.

  • No migrations. The database schema is unchanged from 0.2, so there is nothing to migrate.
  • New, optional environment variables (Node.js and Docker): INGEST_PORT, INGEST_HOST and MAIN_INGEST. Leave them unset and Gooseplicant behaves exactly as before. See Configuration.
  • Gosling only looks different. Its new mark changes nothing you configure: EDITION still takes full or lite, and /ats/lite/ stays where it was.
  • Docker: the image now declares EXPOSE 3000 3001; 3001 is used only with INGEST_PORT=3001. Your Compose file keeps working unchanged.
  • Unchanged: the /ats base path, the X-ATS-* headers your website signs with, the Cloudflare wrangler.toml variables and the ats.db database file.

From 0.1 to 0.2#

0.2 brings Gosling (the Lite edition), import of old applications, zip export and location aliases. The upgrade follows the usual steps below; a few things are worth knowing first.

  • Back up first. As always: there are no down-migrations, so the backup is your way back.
  • Migrations run by themselves. On start, Gooseplicant applies whatever is missing up to 0004. Coming from 0.1.0 that is 0004 (imports without an email address, position folders, export grants); installations from before 0.1.0 also get 0002 (search-index bookkeeping, followed by a one-time background rebuild of the search index) and 0003 (brand theme settings). Each is quick and runs in one batch.
  • Nothing to configure. EDITION defaults to full, so you keep the HR app, and Gosling appears alongside it at /ats/lite/. Your Access policy or proxy already covers that path. Set EDITION=lite only if you want Gosling on its own; see Set the edition.
  • Cloudflare: the new kit's wrangler.toml has an EDITION entry under [vars]. If you copy your old file over, add EDITION = "full" (or leave it out, which means the same).
  • Docker: the image is now tagged gooseplicant. Build it as shown below and change the image: line of your existing Compose file from ats:latest to gooseplicant:latest (the 0.2 example file already says so); the ats service name, the ats-data volume and your .env stay as they are.
  • Unchanged on purpose: the /ats base path, the X-ATS-* headers your website signs with, all environment variables and the ats.db database file. Your careers form keeps working without a change.

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://gooseplicant.goosenotes.dev/downloads/0.3.0/gooseplicant-0.3.0.tar.gz
curl -LO https://gooseplicant.goosenotes.dev/downloads/0.3.0/SHA256SUMS
grep ' gooseplicant-0.3.0.tar.gz$' SHA256SUMS | shasum -a 256 -c
tar -xzf gooseplicant-0.3.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 gooseplicant-0.3.0
docker build -f apps/node/Dockerfile -t gooseplicant:0.3.0 -t gooseplicant:latest .
  2. Recreate the container
    Terminal
    cd ~/ats-deploy
docker compose up -d
docker compose logs -f ats      # watch it start and apply migrations

    Make sure the image: line in docker-compose.yml says gooseplicant:latest. The ats-data volume, your .env and Caddyfile are untouched. To roll back, point image: at the previous version's tag and restore the backup taken before the upgrade.

Node.js#

  1. Unpack next to the current version and install
    Terminal
    sudo tar -xzf gooseplicant-0.3.0.tar.gz -C /opt/ats
cd /opt/ats/gooseplicant-0.3.0
sudo npm ci --omit=dev
  2. Switch over and restart
    Terminal
    sudo ln -sfn /opt/ats/gooseplicant-0.3.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.

Kept your .env inside the app folder? Copy apps/node/.env from the old folder to the new one before restarting, and make sure DATA_DIR is an absolute path, or the new folder starts with an empty ./data.

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 gooseplicant-0.3.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.