Upgrading

Versioning promise

Tyr is pre-1.0 today (see Project status). Breaking changes are possible between minor versions and will be documented in the release notes and CHANGELOG.

Post-1.0, we’ll follow semver:

MAJOR — breaking changes (policy schema, protocol, API).
MINOR — backward-compatible features.
PATCH — bug fixes only.

Image channels

Channel	Example tag	Cadence
Stable	`:latest`, `:v0.5.2`	On GitHub release
Edge	`:edge`, `:main`	On every push to main
Pinned	`:sha-abc1234`	On every push to main

Production: pin to :vX.Y.Z and upgrade deliberately. Dev: :latest is fine.

Upgrading the server

Docker Compose

docker compose pull tyr-server
docker compose up -d tyr-server

Migrations run automatically on startup. The server applies any pending SQL from crates/tyr-server/migrations/ in order.

Kubernetes

kubectl -n tyr-system set image deploy/tyr-server tyr-server=ghcr.io/terranchi/tyr/tyr-server:v0.6.0

One tyr-server replica today — a rolling update isn’t a concern yet. If you’re running multiple replicas manually, do a full stop → upgrade → start cycle on the database tier.

Binary

sudo systemctl stop tyr-server
sudo install tyr-server-new /usr/local/bin/tyr-server
sudo systemctl start tyr-server

Upgrading agents

Agents are older-than-server tolerant — a v0.5 agent keeps working against a v0.6 server. The server advertises its feature set on each gRPC connect; agents only use what they support.

One host

sudo systemctl stop tyr-agent
# Script re-download
curl -sSL https://raw.githubusercontent.com/terranchi/tyr/main/scripts/install.sh | sudo bash -s -- --component agent --skip-enroll
sudo systemctl start tyr-agent

--skip-enroll preserves the existing identity in /var/lib/tyr/.

Fleet (manual)

Run the above over your preferred config-management tool (Ansible, Salt, etc.). The install script is idempotent.

Future: remote agent upgrade

Planned — the server pushes a new version to enrolled agents that auto-apply during a maintenance window. Tracking in a GitHub issue.

Policy schema migrations

If a minor release changes apiVersion: tyr.dev/v1 → v2, existing v1 policies continue to compile on the new server. Future tyr policy migrate will rewrite them in place.

Database migrations

Forward-only. There is no automated down migration.
Test minor upgrades on a staging database first for large event tables.
Event retention (DELETE FROM events WHERE ts < ...) is your responsibility — we don’t auto-prune.

Rollback

If something is badly broken:

# 1. Restore the previous image
docker compose pull ghcr.io/terranchi/tyr/tyr-server:v0.5.2
# or kubectl set image ...

# 2. If migrations ran forward, restore the database from backup
pg_restore -d tyr backup-pre-upgrade.dump

This is why backups before minor upgrades are non-negotiable.

→ Next: Backup & restore · Releases