# Upgrade

`SHELLHUB_VERSION` decides which image tag every service runs. Changing it and recreating the containers is the upgrade; everything else on this page is what to do around that.

> **Careful**
>
> Read the release notes for every version between the one you are on and the one you are moving to. Migrations and breaking changes are announced there and nowhere else.

## Before you start

**Back up.** The database and the secrets, and verify the dump is readable. See [Backup](https://docs.shellhub.io/selfhosted/backup).

**Read the release notes** for every version between where you are and where you are going, not just the target. Migrations and breaking changes live there.

**Know your current version:**

```bash
$ grep SHELLHUB_VERSION .env
```

## The shape of it

Get the new sources:

```bash
$ git fetch --tags
$ git checkout v0.30.4
```

Every tag is on the [releases page](https://github.com/shellhub-io/shellhub/releases), and a release two or three versions ahead is a fine target as long as you read what changed in between.

Your settings survive, because they are in `.env.override` and not in `.env`. If you edited `.env` directly, the checkout has just overwritten your changes — which is why the quickstart says not to.

Then pull and recreate:

```bash
$ ./bin/docker-compose pull
$ make stop
$ make start
```

## Moving the certificates into the server

From 0.29 to the release that runs the gateway inside the server, the certificates and the ACME account move from the gateway container’s volume to the server’s `gateway_data` volume, which starts empty. With `SHELLHUB_AUTO_SSL=true`, carry them over, or the server asks the CA for every certificate again and can hit Let’s Encrypt’s rate limits.

Before the checkout, while the old gateway is still defined, copy its store out:

```bash
$ ./bin/docker-compose cp gateway:/data ./gateway-data
```

After the checkout and the pull, put it in the server’s volume before the server first starts:

```bash
$ make stop
$ ./bin/docker-compose create server
$ ./bin/docker-compose cp ./gateway-data/. server:/data
$ make start
```

Once HTTPS answers on the new release, remove the old gateway container with `./bin/docker-compose up -d --remove-orphans`.

## Afterwards

Check the services are up and the logs are clean:

```bash
$ ./bin/docker-compose ps
$ ./bin/docker-compose logs -f
```

Then check a device actually connects. Services being up is not the same as the product working — open a session before you call it done.

## Agent versions

Agents do not have to match the server, and updating the server does not update them. Snap installs refresh themselves; container and standalone installs stay where they are until you move them.

One hard boundary: the server refuses public-key authentication from agents older than 0.6.0 unless `SHELLHUB_ALLOW_PUBLIC_KEY_ACCESS_BELLOW_0_6_0` is set — note the spelling.

## If it goes wrong

Check the tag back out, pull, and restart. If a migration ran, restore the database from the backup you took — which is why the first instruction on this page is to take one.

## Where to go next

- [Backup](https://docs.shellhub.io/selfhosted/backup) — Do this first.
- [Troubleshooting](https://docs.shellhub.io/selfhosted/troubleshooting) — When it does not come back up.
