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 deployment/server-setup.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.