docs/getting-started/upgrading/index.md

# Upgrading

If your version of Dokku is pre 0.3.0 (check with `dokku version`), we recommend [a fresh install](/docs/getting-started/installation/index.md) on a new server.

## Security Updates

For any security related updates, please follow our [Twitter account](https://twitter.com/dokku). As Dokku does not run any daemons, the security risk introduced by our software is minimal.

Your operating system may occasionally provide security updates. We recommend setting unattended upgrades for your operating system. Here are some helpful links:

- [Arch Linux System Maintenance](https://wiki.archlinux.org/index.php/System_maintenance)
- [Debian Unattended Upgrades](https://wiki.debian.org/UnattendedUpgrades)
- [Ubuntu Unattended Upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates)

Docker releases updates periodically to their engine. We recommend reading their release notes and upgrading accordingly. Please see the [Docker documentation](https://docs.docker.com/) for more details.

## Migration Guides

Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.

- [Upgrading to 0.37](/docs/appendices/0.37.0-migration-guide.md)
- [Upgrading to 0.36](/docs/appendices/0.36.0-migration-guide.md)
- [Upgrading to 0.35](/docs/appendices/0.35.0-migration-guide.md)
- [Upgrading to 0.34](/docs/appendices/0.34.0-migration-guide.md)
- [Upgrading to 0.33](/docs/appendices/0.33.0-migration-guide.md)
- [Upgrading to 0.32](/docs/appendices/0.32.0-migration-guide.md)
- [Upgrading to 0.31](/docs/appendices/0.31.0-migration-guide.md)
- [Upgrading to 0.30](/docs/appendices/0.30.0-migration-guide.md)
- [Upgrading to 0.29](/docs/appendices/0.29.0-migration-guide.md)
- [Upgrading to 0.28](/docs/appendices/0.28.0-migration-guide.md)
- [Upgrading to 0.27](/docs/appendices/0.27.0-migration-guide.md)
- [Upgrading to 0.26](/docs/appendices/0.26.0-migration-guide.md)
- [Upgrading to 0.25](/docs/appendices/0.25.0-migration-guide.md)
- [Upgrading to 0.24](/docs/appendices/0.24.0-migration-guide.md)
- [Upgrading to 0.23](/docs/appendices/0.23.0-migration-guide.md)
- [Upgrading to 0.22](/docs/appendices/0.22.0-migration-guide.md)
- [Upgrading to 0.21](/docs/appendices/0.21.0-migration-guide.md)
- [Upgrading to 0.20](/docs/appendices/0.20.0-migration-guide.md)
- [Upgrading to 0.10](/docs/appendices/0.10.0-migration-guide.md)
- [Upgrading to 0.9](/docs/appendices/0.9.0-migration-guide.md)
- [Upgrading to 0.8](/docs/appendices/0.8.0-migration-guide.md)
- [Upgrading to 0.7](/docs/appendices/0.7.0-migration-guide.md)
- [Upgrading to 0.6](/docs/appendices/0.6.0-migration-guide.md)
- [Upgrading to 0.5](/docs/appendices/0.5.0-migration-guide.md)

## Upgrade Process

### Before upgrading

If you'll be updating docker or the herokuish package simultaneously, it's recommended
that you stop all applications before upgrading and rebuild afterwards. This is not
required if the upgrade only impacts the `dokku` package.

Why do we recommend stopping all apps?

- `docker`: Containers may be randomly reset during the upgrade process, resulting in
  requests being sent to the wrong containers. Acknowledging and scheduling downtime
  thus becomes much more important.
- `herokuish`: While not required, it may be useful to take advantage of the latest
  base image. Herokuish changes do not cause issues unless the base OS changes, which
  may happen in minor or major releases.

```shell
# for 0.22.0 and newer versions, use
dokku ps:stop --all

# for versions between 0.11.4 and 0.21.4, use
dokku ps:stopall

# for versions between 0.8.1 and 0.11.3, use
dokku --quiet apps:list | xargs -L1 dokku ps:stop

# for versions older than 0.8.1, use
dokku --quiet apps | xargs -L1 dokku ps:stop
```

### Upgrading

> [!IMPORTANT]
> Unless specified, the `bootstrap.sh` script installs Dokku via a Debian package (`.deb`). Using either the `dokku-update` or `apt` methods are enough to perform an upgrade of Dokku.

Please read the migration guides for each version in between your currently installed version of Dokku and the version you are upgrading to in order to ensure minimal downtime.

#### Upgrading using `dokku-update`

> [!WARNING]
> The `dokku-update` package currently does not support upgrading to a specific version of Dokku. If this is required by a particular migration guide, use the `apt` method for upgrading.

We provide a helpful binary called `dokku-update`. This is a recommended package that:

- Can be installed separately, so upgrading Dokku will not affect the running of this package.
- Automates many of the upgrade instructions for you.
- Provides a clean way for us to further enhance the upgrade process in the future.

This binary is available on Debian and RPM-based systems from our package repositories under the name `dokku-update`. When installing from source,
this is available from a separate Github repository at [dokku/dokku-update](https://github.com/dokku/dokku-update).

#### Upgrading using `apt`

If Dokku was installed in a Debian or Ubuntu system, via `apt-get install dokku` or `bootstrap.sh`, you can upgrade with `apt-get`:

```shell
# update your local apt cache
sudo apt-get update

# update dokku and its dependencies
sudo apt-get --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener

# or just upgrade every package:
sudo apt-get upgrade
```

To upgrade to a specific version of Dokku, specify it on the `apt-get` call:

```shell
# specify the version _without_ the `v` prefix
sudo apt-get dokku=$VERSION
```

#### Upgrading from source

> [!CAUTION]
> Dokku is not normally installed from source. Executing a source upgrade when the installation was performed via apt package may result in an inoperable system and will require manual work to get Dokku in a working state.

If you installed Dokku from source (less common), upgrade with:

```shell
cd ~/dokku
git pull --tags origin master

# continue to install from source
sudo DOKKU_BRANCH=master make install

# upgrade to debian package-based installation
sudo make install
```

To upgrade Herokuish from source, upgrade with:

```shell
cd /tmp
git clone https://github.com/gliderlabs/herokuish.git
cd herokuish
CIRCLECI=true IMAGE_NAME=gliderlabs/herokuish BUILD_TAG=latest make build/docker
```

### After upgrading

After upgrading, you should rebuild the applications to take advantage of any
new buildpacks that were released:

```shell
dokku ps:rebuild --all
```
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00			`# Upgrading`

docs: rename upgrading index to allow supporting navigation indexes 2022-09-05 17:07:57 -04:00			If your version of Dokku is pre 0.3.0 (check with `dokku version`), we recommend [a fresh install](/docs/getting-started/installation/index.md) on a new server.
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
docs: add notes on patching operating systems for security Refs #1089 2018-01-13 19:26:49 -05:00			`## Security Updates`

Fix Getting Started guides style 2019-02-03 16:04:00 +08:00			`For any security related updates, please follow our [Twitter account](https://twitter.com/dokku). As Dokku does not run any daemons, the security risk introduced by our software is minimal.`
docs: add notes on patching operating systems for security Refs #1089 2018-01-13 19:26:49 -05:00
			`Your operating system may occasionally provide security updates. We recommend setting unattended upgrades for your operating system. Here are some helpful links:`

			`- [Arch Linux System Maintenance](https://wiki.archlinux.org/index.php/System_maintenance)`
			`- [Debian Unattended Upgrades](https://wiki.debian.org/UnattendedUpgrades)`
			`- [Ubuntu Unattended Upgrades](https://help.ubuntu.com/community/AutomaticSecurityUpdates)`

feat: build the dokku-update package Releases can be made by running `contrib/release-dokku-update` 2018-01-21 15:42:34 -05:00			`Docker releases updates periodically to their engine. We recommend reading their release notes and upgrading accordingly. Please see the [Docker documentation](https://docs.docker.com/) for more details.`

Fix formatting on upgrading docs [ci skip] 2016-03-21 01:41:03 -04:00			`## Migration Guides`
Add link to 0.5.x migration guide [ci skip] 2016-03-02 23:10:05 -05:00
condense upgrading instructions + fix broken links 2016-04-20 15:32:52 -05:00			`Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.`
Add link to 0.5.x migration guide [ci skip] 2016-03-02 23:10:05 -05:00
refactor: remove support for DOKKU_DOCKERFILE_CACHE_BUILD This replicates the docker-options functionality. 2025-11-15 23:27:22 -05:00			`- [Upgrading to 0.37](/docs/appendices/0.37.0-migration-guide.md)`
docs: add missing link to 0.36.0 migration guide 2025-11-15 23:21:41 -05:00			`- [Upgrading to 0.36](/docs/appendices/0.36.0-migration-guide.md)`
docs: add a migration guide for Dokku 0.35 2024-09-23 00:55:27 -04:00			`- [Upgrading to 0.35](/docs/appendices/0.35.0-migration-guide.md)`
refactor: simplify file ownership in the container by setting the process ownership during the build process Rather than require a heavy chown operation across various paths, just chown the files already in the built image during the release process. This ensures we can skip not-only the chown process during the container start that herokuish injects, but also the one that Dokku runs which modifies mounted container paths as well during the pre-deploy. Note that users will need to ensure any mounted volumes don't have permissions reset by other processes or containers won't be able to access them. 2024-02-25 14:42:19 -05:00			`- [Upgrading to 0.34](/docs/appendices/0.34.0-migration-guide.md)`
docs: add a reference to the 0.33.x placeholder migration guide 2024-03-12 22:18:52 -04:00			`- [Upgrading to 0.33](/docs/appendices/0.33.0-migration-guide.md)`
docs: add a migration guide for 0.32.x 2023-08-19 12:26:21 -04:00			`- [Upgrading to 0.32](/docs/appendices/0.32.0-migration-guide.md)`
refactor: move herokuish app cache from the filesystem into a docker volume This simplifies cache referencing and also paves the way for removing more from the app git directory. Refs #1558 2022-11-28 02:24:27 -05:00			`- [Upgrading to 0.31](/docs/appendices/0.31.0-migration-guide.md)`
chore: drop SPDY This hasn't been supported by browsers in quite a while and nginx will set a warning as of Ubuntu 20.04 when the header is referenced. 2022-12-29 01:59:54 -05:00			`- [Upgrading to 0.30](/docs/appendices/0.30.0-migration-guide.md)`
feat: use container name instead of container id for run:detached output Closes #5170 2022-08-22 21:49:54 -04:00			`- [Upgrading to 0.29](/docs/appendices/0.29.0-migration-guide.md)`
docs: add missing upgrade guide 2022-08-22 21:47:54 -04:00			`- [Upgrading to 0.28](/docs/appendices/0.28.0-migration-guide.md)`
fix: only rename app domains associated with a global domain Closes #4965 2022-01-28 22:38:24 -05:00			`- [Upgrading to 0.27](/docs/appendices/0.27.0-migration-guide.md)`
feat: implement the scheduler plugin This also performs a one-time migration of the DOKKU_SCHEDULER values the scheduler plugin properties. Closes #4739 2021-10-09 17:44:35 -04:00			`- [Upgrading to 0.26](/docs/appendices/0.26.0-migration-guide.md)`
			`- [Upgrading to 0.25](/docs/appendices/0.25.0-migration-guide.md)`
docs: fix doc link and add 0.24.0 appendix to migration guides [ci skip] 2021-03-01 12:01:26 -05:00			`- [Upgrading to 0.24](/docs/appendices/0.24.0-migration-guide.md)`
refactor: remove need for internal dokku calls Avoid internal dokku calls will avoid potentially expensive subprocesses - in particular, user-auth will be re-invoked, which can be expensive. 2021-01-23 12:32:31 -05:00			`- [Upgrading to 0.23](/docs/appendices/0.23.0-migration-guide.md)`
feat: prohibit non-dns names for apps and process types This is necessary for ensuring ssl certificates can be auto-retrieved for apps, and also easing integration into schedulers that use names and process types as part of DNS records. As well, this fixes an issue where we may potentially have invalid DNS entries when adding apps to custom networks. Closes #4102 Closes #4114 2020-09-09 20:06:53 -04:00			`- [Upgrading to 0.22](/docs/appendices/0.22.0-migration-guide.md)`
docs: add 0.21.0 migration guide [ci skip] 2020-07-14 15:08:33 -04:00			`- [Upgrading to 0.21](/docs/appendices/0.21.0-migration-guide.md)`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00			`- [Upgrading to 0.20](/docs/appendices/0.20.0-migration-guide.md)`
			`- [Upgrading to 0.10](/docs/appendices/0.10.0-migration-guide.md)`
			`- [Upgrading to 0.9](/docs/appendices/0.9.0-migration-guide.md)`
			`- [Upgrading to 0.8](/docs/appendices/0.8.0-migration-guide.md)`
			`- [Upgrading to 0.7](/docs/appendices/0.7.0-migration-guide.md)`
			`- [Upgrading to 0.6](/docs/appendices/0.6.0-migration-guide.md)`
			`- [Upgrading to 0.5](/docs/appendices/0.5.0-migration-guide.md)`
Update upgrading.md 2016-03-28 21:09:37 -05:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`## Upgrade Process`

			`### Before upgrading`
docs: add links to migration guides [ci skip] 2017-08-09 17:07:06 -04:00
docs: clarify why we stop/rebuild apps during upgrade [ci skip] 2020-07-14 19:48:10 -04:00			`If you'll be updating docker or the herokuish package simultaneously, it's recommended`
			`that you stop all applications before upgrading and rebuild afterwards. This is not`
			required if the upgrade only impacts the `dokku` package.

			`Why do we recommend stopping all apps?`

			- `docker`: Containers may be randomly reset during the upgrade process, resulting in
			`requests being sent to the wrong containers. Acknowledging and scheduling downtime`
			`thus becomes much more important.`
docs: expand docs around herokuish upgrades Refs https://github.com/dokku/dokku/pull/4063#discussion_r460257032 [ci skip] 2020-07-28 15:12:51 -04:00			- `herokuish`: While not required, it may be useful to take advantage of the latest
			`base image. Herokuish changes do not cause issues unless the base OS changes, which`
			`may happen in minor or major releases.`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
Use shell keyword for codeblock guard 2014-12-19 15:09:38 -05:00			```shell
chore: drop all references to `all` commands where possible. 2020-11-21 17:31:25 -05:00			`# for 0.22.0 and newer versions, use`
Update upgrading.md Add command for versions 0.22 and higher 2020-12-17 17:15:15 +01:00			`dokku ps:stop --all`
chore: drop all references to `all` commands where possible. 2020-11-21 17:31:25 -05:00
			`# for versions between 0.11.4 and 0.21.4, use`
Replace docs using manual stopping of all apps with ps:stopall cmd 2018-01-19 00:37:26 +08:00			`dokku ps:stopall`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
Replace docs using manual stopping of all apps with ps:stopall cmd 2018-01-19 00:37:26 +08:00			`# for versions between 0.8.1 and 0.11.3, use`
docs: update uninstallation docs to clarify which subcommand to use for listing applications [ci skip] 2017-08-19 19:03:20 -04:00			`dokku --quiet apps:list \| xargs -L1 dokku ps:stop`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
docs: fix typo in `getting-started/upgrading/index.md` the word, 'versions,' was repeated. 2023-05-27 14:40:05 +01:00			`# for versions older than 0.8.1, use`
docs: update uninstallation docs to clarify which subcommand to use for listing applications [ci skip] 2017-08-19 19:03:20 -04:00			`dokku --quiet apps \| xargs -L1 dokku ps:stop`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00			```
docs: update uninstallation docs to clarify which subcommand to use for listing applications [ci skip] 2017-08-19 19:03:20 -04:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`### Upgrading`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`> [!IMPORTANT]`
			> Unless specified, the `bootstrap.sh` script installs Dokku via a Debian package (`.deb`). Using either the `dokku-update` or `apt` methods are enough to perform an upgrade of Dokku.
docs: update uninstallation docs to clarify which subcommand to use for listing applications [ci skip] 2017-08-19 19:03:20 -04:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`Please read the migration guides for each version in between your currently installed version of Dokku and the version you are upgrading to in order to ensure minimal downtime.`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			#### Upgrading using `dokku-update`

			`> [!WARNING]`
			> The `dokku-update` package currently does not support upgrading to a specific version of Dokku. If this is required by a particular migration guide, use the `apt` method for upgrading.
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
			We provide a helpful binary called `dokku-update`. This is a recommended package that:

			`- Can be installed separately, so upgrading Dokku will not affect the running of this package.`
			`- Automates many of the upgrade instructions for you.`
			`- Provides a clean way for us to further enhance the upgrade process in the future.`

Update source for `dokku-update` The `dokku-update` tool has been extracted into it's own repository, and is no longer available inside the `dokku` source. 2021-09-13 20:42:41 -04:00			This binary is available on Debian and RPM-based systems from our package repositories under the name `dokku-update`. When installing from source,
			`this is available from a separate Github repository at [dokku/dokku-update](https://github.com/dokku/dokku-update).`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			#### Upgrading using `apt`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
refactor: standardize apt-get usage - Always put flags in same location - Always use apt-get - Add --no-install-recommends where possible 2021-01-17 16:09:58 -05:00			If Dokku was installed in a Debian or Ubuntu system, via `apt-get install dokku` or `bootstrap.sh`, you can upgrade with `apt-get`:
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
			```shell
			`# update your local apt cache`
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`sudo apt-get update`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
			`# update dokku and its dependencies`
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			`sudo apt-get --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00
			`# or just upgrade every package:`
refactor: standardize apt-get usage - Always put flags in same location - Always use apt-get - Add --no-install-recommends where possible 2021-01-17 16:09:58 -05:00			`sudo apt-get upgrade`
Rewrite upgrade instructions 2020-07-14 18:59:57 +01:00			```

docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00			To upgrade to a specific version of Dokku, specify it on the `apt-get` call:

			```shell
			# specify the version _without_ the `v` prefix
			`sudo apt-get dokku=$VERSION`
			```

			`#### Upgrading from source`

			`> [!CAUTION]`
			`> Dokku is not normally installed from source. Executing a source upgrade when the installation was performed via apt package may result in an inoperable system and will require manual work to get Dokku in a working state.`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
Use correct casing for Dokku name lowercase should only be used to refer to the binary, not the project 2016-09-03 04:39:12 -04:00			`If you installed Dokku from source (less common), upgrade with:`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
[ci skip] update upgrade documentation for 0.3.18 2015-04-18 02:48:44 -04:00			```shell
			`cd ~/dokku`
			`git pull --tags origin master`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
[ci skip] update upgrade documentation for 0.3.18 2015-04-18 02:48:44 -04:00			`# continue to install from source`
			`sudo DOKKU_BRANCH=master make install`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
[ci skip] update upgrade documentation for 0.3.18 2015-04-18 02:48:44 -04:00			`# upgrade to debian package-based installation`
			`sudo make install`
			```
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
Fix Getting Started guides style 2019-02-03 16:04:00 +08:00			`To upgrade Herokuish from source, upgrade with:`
Consolidate readme/wiki docs into organized docs folder 2014-10-04 04:24:22 -04:00
[ci skip] update upgrade documentation for 0.3.18 2015-04-18 02:48:44 -04:00			```shell
			`cd /tmp`
initial pass at switching to herokuish. closes #1091 2015-04-20 16:32:18 -07:00			`git clone https://github.com/gliderlabs/herokuish.git`
			`cd herokuish`
docs: update herokuish upgrade instructions Closes #4944 2021-11-24 18:40:53 +07:00			`CIRCLECI=true IMAGE_NAME=gliderlabs/herokuish BUILD_TAG=latest make build/docker`
[ci skip] update upgrade documentation for 0.3.18 2015-04-18 02:48:44 -04:00			```
docs: clarify to users that the migration guides should be followed for upgrades Refs #7018 2024-07-30 13:19:10 -04:00
			`### After upgrading`

			`After upgrading, you should rebuild the applications to take advantage of any`
			`new buildpacks that were released:`

			```shell
			`dokku ps:rebuild --all`
			```