Skip to content

Upgrading Doable

The shape of an upgrade depends on the deployment style.

Pre-upgrade — every time

  1. Read the changelog (CHANGELOG.md if present, otherwise the GitHub release notes).
  2. Take a backup — DB and PROJECTS_ROOT/. See Backups.
  3. Pin the new commit/tag so a rollback is easy.

Docker upgrade

cd doable
git fetch --tags
git checkout v<new-version>           # or 'main' if you live on the edge
docker compose -f docker/docker-compose.yml up --build -d
docker compose -f docker/docker-compose.yml run --rm migrate

Watch the logs for a minute:

docker compose -f docker/docker-compose.yml logs -f

If something is wrong:

git checkout v<previous-version>
docker compose -f docker/docker-compose.yml up --build -d
# If migrations were destructive, restore the DB backup as well.

Bare-metal upgrade

cd /root/doable
git fetch --tags
git checkout v<new-version>
pnpm install
pnpm db:migrate
sudo systemctl restart doable

Tail logs:

journalctl -u doable -f

After the upgrade

  • Confirm /health returns 200 OK.
  • Smoke-test: log in, open a project, send a chat message, publish a project.
  • Check Workspace Settings → Audit for any new error entries.

Major version upgrades

Major versions may include:

  • Breaking schema changes that need an offline migration.
  • Renamed env vars — read the changelog and update .env.
  • New required env vars — Docker compose will fail fast; bare-metal will error in the API logs.
  • New required system packages — re-run setup-server.sh if so noted.

Rolling upgrades for multi-instance deployments

If you run multiple API replicas:

  1. Take one replica out of the load balancer.
  2. Pull, install, restart it.
  3. Smoke-test.
  4. Put it back in. Take the next out. Repeat.
  5. Run migrations exactly once, ideally from the first upgraded replica.

Schema migrations are designed to be backward-compatible across one minor version, so the old replicas keep working while the new ones come up. For breaking schema changes (rare), use the expand → migrate → contract pattern across two deploys.

Updating just the AI / Copilot SDK

The Copilot SDK is pinned in package.json (@github/copilot-sdk). To update only that:

pnpm up @github/copilot-sdk -L
pnpm install
sudo systemctl restart doable    # or: docker compose up --build -d

If the SDK adds new event kinds, you'll see them flow through event-mapper.ts as unknown events until you map them — a non-fatal warning will appear in the API log.

Downgrading

cd doable
git checkout v<old-version>
# Restore the matching DB dump from BEFORE the upgrade.
# Restore PROJECTS_ROOT if a destructive operation touched files (rare).
docker compose -f docker/docker-compose.yml up --build -d   # or systemctl restart doable

Always pair a code rollback with the matching DB rollback if the upgrade ran any migrations.