title: “Upgrade” sidebar_position: 3 description: How to upgrade your Apache DevLake to a newer version

Upgrade Options

Option 1: Update the image tags to a newer version

This is recommended way to upgrade your instance, it is the easiest way to go. However, the docker-compose.yml or the helm chart might change over time (e.g., a new persistent volume is required for new feature to work properly), you may have to adopt these changes manually or opt for the next option.

Option 2: Deploy a new instance while keeping the configuration

  1. Dump the .env file from the existing devlake container and shut it down
  2. Fire up the new container with the .env file mounted to the correct path

Two Things to Note

  1. Database migration. Starting from Release v0.10.0 ยท apache/incubator-devlake, DevLake auto-migrates your table schema and records to the newer version. Normally you don‘t need to do anything for the migration. However, please keep in mind the migration is one-way only, downgrade is not supported. Please consider backing up your database if there’s any data you'd like to keep.

  2. Preserve the .env file. DevLake reads and writes some configurations from/to the .env file. An example is the ENCODE_KEY generated by the devlake container during the first boot. ENCODE_KEY is used to encrypt sensitve information in the database, e.g., personal access tokens and passwords. Normally, users don't need to worry about the .env file during upgrade. But in the following scenarios, users may want to back up the .env file:

    1. When a user deploys a new DevLake instance and points it to an existing cloud managed database. Since the existing database is encrypted with the ENCODE_KEY in the .env file, the user needs to port the old .env file to the new DevLake instance.
    2. When a user deploys DevLake to AWS ECS but did not properly persist the .env file.

    To back up .env file, users can log into the devlake container and dump the file somewhere else. The file path in the container is /app/.env or /app/config/.env if you were using helm (unless the ENV_PATH environment variable is specified).