Update your Shlink instance

Shlink is designed so that updating an installation to a newer version is as easy as possible, without loosing any data while doing it.

However, the process may defer depending on how you installed Shlink.

Important

It is recommended that you don’t skip too many versions at a time when updating Shlink. If you have to, make sure to back-up your database beforehand, in case the process needs to be rolled back.

If your Shlink instance is out of date, preferably update Shlink in sequential order using the latest patch release for every minor version. For example, to go from version 3.2.1 to version 3.4.0, first update to 3.3.2, and then 3.4.0.

Update a docker image

This is probably the simplest use case.

When a new shlink version is released, it will come together with a new docker image tag.

You will just need to use the new one in order to get updated. The image itself will take care of updating the database, if needed, without loosing data in the process.

Env vars will be backwards compatible, and only major releases may drop support for some of existing ones, but when this happens, documentation will be provided on how to migrate.

Updating a self-hosted instance.

If you are hosting Shlink manually, you probably started by running the install command of the installation tool (vendor/bin/shlink-installer install), which gets your instance set-up.

This tool also has an update command (vendor/bin/shlink-installer update). With it, you will be able to import the configuration from your previous installation folder, and provide any new configuration options. Any configuration option you previously provided will be kept the same.

That said, the process you should follow would be this:

  1. Rename your existing Shlink directory to something else (ie. shlink -> shlink-old).
  2. Download and extract the new version of Shlink, and set the directory name to that of the old version (ie. shlink).
  3. Run the vendor/bin/shlink-installer update script in the new version’s directory to migrate your configuration over. You will be asked to provide the path to the old instance (ie. shlink-old).
  4. Restart the service (either Shlink if you are using RoadRunner, or the web server of your choice).