# Upgrading

Update kogut and recover from a failed upgrade.

Read **What to change** at the top of the release notes of every version after yours,
and take a [backup](https://docs.kogut.dev/high-availability/backups/) before a minor upgrade, with
`kogut.toml` and its secrets
([What to back up](https://docs.kogut.dev/high-availability/backups/#what-to-back-up)). Update the server
first, then agents ([Agent compatibility](#agent-compatibility)).

You can upgrade from any release since 0.1.0 straight to the latest. Each release is
tested on the databases that all earlier releases wrote.

## Update your installation

**Install script**

Run the installer again and restart the service:

```sh
curl -fsSL https://kogut.dev/install | sh
sudo systemctl restart kogut
```

The installer keeps your data and systemd drop-ins. For a specific version, run
`curl -fsSL https://kogut.dev/install | KOGUT_VERSION=0.1.2 sh`
([install-script variables](https://docs.kogut.dev/reference/environment-variables/#install-script)).

For agents, rerun the installer with `agent --server <url> --token <token>` and restart
`kogut-agent`. The connection settings are in `/etc/kogut/agent.env`.

**Docker**

Pull the image and recreate the container with the same volume, environment, mounts,
and options. For the basic setup:

```sh
docker pull ghcr.io/piotrkowski/kogut:0.1
docker stop kogut
docker rm kogut
docker run -d --name kogut --restart unless-stopped \
  -p 8484:8484 -v kogut-data:/data \
  -e KOGUT_URL=http://localhost:8484 \
  ghcr.io/piotrkowski/kogut:0.1
```

Replace the URL with the one you use to open kogut.

**Docker Compose**

```sh
docker compose pull
docker compose up -d
```

With named Compose files, pass the same `-f` arguments to both commands.

**Platforms**

Redeploy Dokploy, Coolify, Railway, or Render to pull the template's image tag. For
CapRover, change the image tag in **Deployment** and deploy.

**NixOS**

If you pinned the input to a release tag, change the tag first:

```sh
nix flake update kogut
sudo nixos-rebuild switch
```

The `0.1` image tag tracks 0.1.x patches; a full tag such as `0.1.0` pins a release. A
new minor version needs a new tag.

## Recover from a failed upgrade

Before migrating an existing database, kogut saves a copy beside it, such as
`kogut.db.pre-0002.bak`. An older binary refuses a database with a newer schema.

Stop kogut, restore a compatible backup
([Backups and restore](https://docs.kogut.dev/high-availability/backups/)), and start the previous release.
Data written after that backup is lost.

## Agent compatibility

An agent never has to be newer than its server. A server from a new minor release keeps
accepting agents from the previous minor release for at least 30 days after it ships.
Update your agents within that time.

The release notes say when a feature needs a newer agent. An older agent skips check
types and options it does not know, logs a warning with "update the agent", and keeps
running its other checks.

## Check agents and configuration

Host pages show agent versions. Agents buffer unsent data during a server restart, and
discard it past the buffer's age or size limit
([agent settings](https://docs.kogut.dev/reference/environment-variables/#agent)).

Apply **What to change** before starting the new version. An invalid file prevents
startup; an invalid reload keeps the last valid configuration
([File handling](https://docs.kogut.dev/reference/configuration/#file-handling)).

## Update kogut edge

Update the Worker separately; see
[kogut edge](https://docs.kogut.dev/high-availability/kogut-edge/#update-the-worker).