Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      The Things Stack Enterprise

      • Overview
      • AWS
      • Kubernetes
      • Docker
        • Configuration
        • Certificates
        • Running The Things Stack
        • Proxy
        • Troubleshooting Installation
        • Upgrading The Things Stack
        • Balena
      • The Things Join Server
      • Manage The Things Stack
      Enterprise Open Source

      Upgrading The Things Stack

      Updated 20 January 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      This section contains instructions to upgrade a The Things Stack Enterprise or Open Source deployment.

      Note:

      To avoid downtime in production deployments, we strongly suggest The Things Stack users to test the upgrading process in their staging environments first. After confirming that the upgrade process was successful in staging environment, you may proceed with upgrading The Things Stack in your production deployment.

      Pulling new images

      Replace the tag in your docker-compose.yml file with the newer version of The Things Stack.

      • Enterprise
      • Open Source
      # file: docker-compose.yml
      services:
        # ...
        stack:
          image: "thethingsindustries/lorawan-stack:<new-version-tag>"
        # ...
      
      # file: docker-compose.yml
      services:
        # ...
        stack:
          image: "thethingsnetwork/lorawan-stack:<new-version-tag>"
        # ...
      

      Pull the docker images of the new version.

      docker compose pull stack
      Pulling stack     ... done
      

      The new version will be pulled locally but not run yet.

      Backup

      Warning:

      We do not recommend manually backing up and restoring databases for production deployments. Consider using a managed database service with support for snapshots.

      Stop The Things Stack container.

      docker compose stop stack
      Stopping <directory>_stack_1 ... done
      

      Note:

      In this guide, <directory> represents the directory containing The Things Stack files, i.e. the directory where you cloned The Things Stack repository.

      Redis

      Navigate to the Redis data folder, which can be found in the docker-compose.yml for the redis service (ex: ${DEV_DATA_DIR:-.env/data}/redis)

      Stop the redis container.

      docker compose stop redis
      Stopping <directory>_redis_1 ... done
      

      Copy the ${DEV_DATA_DIR:-.env/data}/redis/appendonly.aof file to a location of your choice. This file is now a snapshot of the database at the time that it is copied.

      To restore redis from this file, simply place the file back in the data folder (replacing the appendonly.aof file) and start redis. The contents of the backup will be read and restored.

      Start the redis container.

      docker compose up -d redis
      Starting <directory>_redis_1 ... done
      

      PostgreSQL

      Keep the postgres container running and make a PostgreSQL backup file using the following command:

      docker exec -it <directory>_postgres_1 /usr/bin/pg_dump --format=c ttn_lorawan > <location-of-your-choice>/postgres-backup.sql
      

      A postgres-backup.sql file containing a snapshot of the PostgreSQL database at the time that it was backed up will be created in the <location-of-your-choice> directory.

      In order to make the backup file available inside the container, just copy the postgres-backup.sql file to the ${DEV_DATA_DIR:-.env/data}/postgres directory on your machine. You can also use the following command to copy the file into the /var/lib/postgresql/data directory inside the container:

      docker cp postgres-backup.sql <directory>_postgres_1:/var/lib/postgresql/data
      

      In order to restore the PostgreSQL database contents, you first need to delete (or rename) the old ttn_lorawan database to prevent conflicts. In order to perform deletion or renaming, you have to be disconnected from the ttn_lorawan database.

      Create a temporary database temp_db:

      docker exec -it <directory>_postgres_1 psql -d ttn_lorawan -c "CREATE DATABASE temp_db;"
      

      Run the following command to disconnect from ttn_lorawan:

      docker exec -it <directory>_postgres_1 psql -d ttn_lorawan -c "SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'ttn_lorawan' AND pid <> pg_backend_pid();"
      

      Now connect to temp_db and delete the old ttn_lorawan database with:

      docker exec -it <directory>_postgres_1 psql -d temp_db -c "DROP DATABASE ttn_lorawan;"
      

      Recreate the ttn_lorawan database:

      docker exec -it <directory>_postgres_1 psql -d temp_db -c "CREATE DATABASE ttn_lorawan;"
      

      At this point, the ttn_lorawan database will be empty. Finally, you can restore the database contents from the postgres-backup.sql snapshot file:

      docker exec <directory>_postgres_1 pg_restore -d ttn_lorawan /var/lib/postgresql/data/postgres-backup.sql
      

      For additional info, please refer to the official PostgreSQL documentation for the specific version that you are using.

      Optional

      Updates to The Things Stack do not modify static (user-uploaded) assets. But those can be backed up as well.

      User profile pictures and end device pictures are stored in the assets folder by default.

      Check the values set for is.profile-picture.bucket-url and is.end-device-picture.bucket-url configuration options to find these locations (if you are using a non-default location).

      You can now copy the contents of those folders to a location of your choice.

      Migrations

      New minor versions of The Things Stack include new features/fixes which may require an update to the databases. This is done through migrations.

      • Enterprise
      • Open Source

      Migrate the Identity Server Database.

      docker compose run --rm stack is-db migrate
      

      Migrate the Network Server Database.

      docker compose run --rm stack ns-db migrate
      

      Migrate the Device Claiming Server Database.

      docker compose run --rm stack dcs-db migrate
      

      Migrate the Application Server Database.

      docker compose run --rm stack as-db migrate
      

      Migrate the Network Operations Center Database.

      docker compose run --rm stack noc-db migrate
      

      Migrate the Identity Server Database.

      docker compose run --rm stack is-db migrate
      

      Migrate the Network Server Database.

      docker compose run --rm stack ns-db migrate
      

      Running the new version

      Once the above steps are successfully completed, start The Things Stack.

      docker compose up -d stack
      

      Troubleshooting

      For common issues that might show up during the upgrade process, see the Troubleshooting Installation section.

      ← Troubleshooting Installation Balena →

      On this page

      • Pulling new images
      • Backup
      • Migrations
      • Running the new version
      • Troubleshooting

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories