Upgrade an instance

An upgrade is a restart with newer code. Tradr keeps all its state in Postgres, so the containers are replaceable and the volume is not. Migrations run by themselves when the api boots.

Back up first, every time. Migrations are forward-only, so an upgrade changes the schema in a way you cannot undo by starting the old container again.

Hosted only

app.tradr.cloud is upgraded for you, from the same published artifacts self-hosters pull. There is no separate hosted version.

Before you start

1. Take a backup. Follow Back up and restore.
2. Read the release notes at github.com/madmatt112/tradr/releases. Breaking changes are announced there.
3. Note the version you are on. You need it to go back.

curl -fsS http://localhost:8080/api/health

Expected result: {"status":"ok","version":"v0.5.4"} on a pinned release.

The release workflow bakes the version into the api image, and /api/health reports it. A locally built image has no version to report. The field is then omitted and you get {"status":"ok"}. Check out a release tag if you want a version you can name.

Whichever image you run, docker compose ps shows the tag it came from:

docker compose ps --format '{{.Service}}\t{{.Image}}'

Do not set APP_VERSION in .env

The api reads .env through compose’s env_file:, and env_file overrides the value baked into the image. An APP_VERSION= line that is present but blank therefore erases the released version, and /api/health silently drops its version field.

.env.example ships the line commented out. If your .env predates that, comment it out.

Open tabs during an upgrade

A running tab does not need a manual reload after an upgrade. On an image that carries APP_VERSION, each tab checks the served version about every five minutes while it is visible. It also checks again as soon as you return to the tab. When the served version differs from the version the tab started with, Tradr shows an update prompt. Select Reload to move to the new version. You lose anything unsaved on the page.

A part of a page can fail to load after an upgrade, because its code file no longer exists on the new version. Tradr reloads the tab one time by itself to recover. If the reload does not recover the page, Tradr shows a prompt with a Reload button instead.

A locally built image has no APP_VERSION and reports no version (see the note above). A tab on such an image does not check for updates and shows no prompt. The value localdev is reserved. A tab treats localdev as an unset version, and also shows no prompt.

The container carries a file named /_headers. This file is a Cloudflare Pages cache policy for the hosted deployment only. The container does not serve the file, and a self-hosted stack does not use it. You can ignore it.

A proxy in front of the container must obey the cache headers

Tradr sets no-store on /config.js and no-cache on index.html, so the container is correct on its own. A reverse proxy or CDN in front of the container must obey these two directives. If the proxy keeps an old copy of index.html, the tab holds the version it started with, while /config.js reports the new served version. The two versions never agree, and the update prompt returns after every reload. To correct this, change the cache configuration of the proxy. For a proxy in front of the stack, see Put TLS in front of the stack.

Which version bump matters

Tradr is pre-1.0, so the usual semver reading is inverted:

Bump	Example	What it means today
Minor	0.5.4 → 0.6.0	A breaking change. Read the release notes before upgrading.
Patch	0.5.3 → 0.5.4	Everything else — features, fixes, UI.

The full policy, and what counts as a breaking change, is in docs/versioning.md.

Path 1 — rebuild from source

The shipped docker-compose.yml builds both images locally, so this is the default path.

git pull
docker compose up -d --build

Compose rebuilds api and web, then recreates the two containers. postgres keeps running, and the pgdata volume is untouched.

Expected result: Compose reports Container tradr-api-1 Started and Container tradr-web-1 Started. With a warm build cache this takes seconds.

This path tracks whatever is on main. Check out a release tag first if you want a specific version:

git fetch --tags
git checkout v0.5.4
docker compose up -d --build

Path 2 — pinned images

Each release publishes multi-arch images to the GitHub Container Registry. Pin them if you want to choose your upgrade window rather than track main.

Replace each service’s build: block in docker-compose.yml with an image:

services:
  api:
    image: ghcr.io/madmatt112/tradr-api:0.5.4
  web:
    image: ghcr.io/madmatt112/tradr-web:0.5.4

Then upgrade by editing the tag and pulling:

docker compose pull
docker compose up -d

Expected result: Compose pulls both images and recreates the containers. Your data survives — the volume is not part of the image.

Pin an exact version. :latest moves on every release, which turns an upgrade into something that happens to you.

Pinning v0.5.3 or earlier needs one edit to .env

v0.5.4 and later need nothing. Skip this if you pin a current release.

Every release through v0.5.3 fails to start against the .env that .env.example and docker/quickstart.sh produce. The api exits immediately with a Zod error naming ENCRYPTION_KEY_PREVIOUS, and Compose restarts it in a loop. The web container answers 502 Bad Gateway throughout.

Those releases shipped the key present but blank, and their config schema rejected a blank value. Comment the line out before you start one:

# ENCRYPTION_KEY_PREVIOUS=

Expected result: the api reaches healthy within about 30 seconds.

ENCRYPTION_KEY_PREVIOUS is only read during key rotation, so commenting it out costs nothing. Upgrading to v0.5.4 is the better fix.

What happens on restart

The api runs migrations during boot, before it serves a single request.

1. It takes a PostgreSQL advisory lock, so only one container migrates at a time.
2. It applies any pending schema migrations, in order.
3. It applies any pending post-migrations — index builds that cannot run inside a transaction.
4. It starts serving.

The api healthcheck allows a 180-second start_period for this. A first-run index build on a large positions table can take minutes, and the grace window keeps Docker from killing the container part-way through.

During the window docker compose ps reports health: starting, and requests through web may return 502 Bad Gateway. Both are expected. restart: unless-stopped does not interrupt a migration in flight.

Details are in Database & migrations.

Verify the upgrade

docker compose ps

Expected result: api reports Up … (healthy), postgres reports Up … (healthy), and web reports Up.

curl -fsS http://localhost:8080/api/health

Expected result: {"status":"ok","version":"v0.5.4"}, naming the version you moved to. A 503 with {"status":"error"} means the api is up but cannot reach the database.

docker compose exec api tradr migrate --status

Expected result: exit code 0, and output ending in Schema is up to date.

Standard migrations (drizzle.__drizzle_migrations):
  table exists: true
  applied: 24
  pending: none
Post-migrations (_post_migrations_journal):
  table exists: true
  applied: 1
  pending: none
Advisory locks:
  migrations (7064001) held: false
  post-migrations (7064002) held: false
Schema is up to date.

Exit code 1 means migrations are pending. Exit code 2 means the command cannot reach the database.

Then log in and open a position you already had. That checks the whole path, which /api/health does not.

Go back to the previous version

Redeploy the version you came from. Set the previous tag, or check out the previous commit, and start the stack again.

# pinned images
docker compose pull
docker compose up -d

# built from source
git checkout v0.5.3
docker compose up -d --build

This works because the schema stays ahead of the code and the older code still runs against it. Contributors are required to add before they remove, so a release adds columns and a later release drops them.

A rollback does not undo the migration. There are no down-migrations. What you are doing is running older code against a newer schema.

Two limits follow:

• A release that drops something ends the range. Once a release removes a column an earlier version still reads, you cannot go back past it. Release notes say so when it happens.
• A rollback does not restore data. Rows written by the newer version stay. Restore a backup if you need the data back as well as the code.

Upgrading a large instance

SKIP_POST_MIGRATIONS=true stops the api from building indexes during boot, so a large instance starts serving without waiting.

Leave it false on a Compose instance. The published image ships no command to apply the work it skips, so the indexes stay missing and queries stay slow. The setting exists for operators who run migrations out of band from a source checkout.

Troubleshooting

• api sits at health: starting and web returns 502 — a migration is running. Allow the full 180 seconds, and watch it with docker compose logs -f api.
• api restarts in a loop, naming ENCRYPTION_KEY_PREVIOUS — you are on a release through v0.5.3. Comment the line out in .env, or upgrade to v0.5.4.
• api restarts in a loop, naming the encryption key — ENCRYPTION_KEY changed, or ENCRYPTION_KEY_FINGERPRINT no longer matches it. Restore the original value.
• tradr migrate --status exits 1 after an upgrade — the api has not finished booting, or it crashed before migrating. Read docker compose logs api.
• docker compose pull reports there is nothing to pull — the services still carry build: blocks. Use path 1, or pin images as in path 2.
• The corner badge still shows the old version — the browser is serving a cached SPA. Reload without cache.

Next steps

• Back up and restore — do this before each upgrade.
• Database & migrations — what runs, in what order, and under which lock.
• Install with Docker Compose — the stack this page assumes.