Skip to content

Docker stack upgrade 2025

Jump to bottom
Wojciech Frącz edited this page Jan 20, 2026 · 11 revisions

TL;DR

After August 2025 we will drop support for MySQL v5 and will require Docker v24+ and Docker Compose v2.25+. At the end of December we will drop support for for ARMv6 and ARMv7 x32 architectures. You should upgrade.

Changes

After August 2025 there will be some backward icompatible changes released.

  • We will drop support for MySQL v5.x that was initially installed on Docker configurations since 2018 (!).
  • We will adjust configuration files to be compliant with Docker v24+ and Docker Compose v2.25+.

At the end of December 2025 we will also drop support for ARM x32 v6 and ARM x32 v7 architectures. Mostly they are x32 Raspbians. That means we WILL NOT release any new SUPLA Cloud version targetting these architectures from 2026 onwards.

Since the version v25.05 we deprecated support for MySQL v5 and the separate docker-compose.ARCHITECTURE.yml configurations. Since v25.03 we use a multi architecture builds that should automatically detect the platform you are using and this in turn required us to upgrade the database containers (which is a good move by the way).

Technically, it it possible to stick with MySQL v5 and most of the features should work, though it's not recommended. We will stop paying attention to the support for MySQL v5 after August 2025. We will release a configuration that might not work on older Docker infrastructure than claimed above in September 2025. We will stop to release ARMv7 containers with SUPLA in 2026, too, so in order to run it on such devices you will have to build it yourself.

The current recommended OS for running SUPLA containers is 'x86_64' / 'amd64' or arm64 / aarch64. The first one corresponds to most of the VPS / private server Linux distributions. The second one corresponds to the Raspberry Pi OS (64 bit) and family, which you should upgrade your Raspberry to, if you are using it.

You can check your current architecture with uname -m command.

Regarding proxy and Let's Encrypt certificates, we now recommend using Nginx Proxy Manager, as you may also read in the installation instructions. Changing the proxy is not required.

New installations on x32 architectures will fail.

How to upgrade

Based on the version of your Docker, you might need to replace docker compose with docker-compose (with hyphen) below. After the upgrade, only docker compose (as a plugin) will be used.

  1. Make sure the current instance is running. Create a database backup. Store it in a safe place. 
    ./supla-docker/supla.sh backup
  2. Stop and remove the containers. 
    cd supla-docker && docker compose down
  3. OPTIONAL BUT RECOMMENDED: If you stick with your system (i.e. it meets the requirements described above), you can free up space taken by previous containers with the following command. 
    docker system prune -fa
  4. Rename current supla-docker to supla-docker-old. 
    mv supla-docker supla-docker-old
  5. Clone the repository again while NOT being inside the supla-docker-old. 
    git clone https://github.com/SUPLA/supla-docker.git
  6. Generate new config. 
    ./supla-docker/supla.sh
  7. Review the settings in ./supla-docker/.env file. Make necessary changes to match the old configuration (domain, ports, MQTT settings, enable proxy if used before). Make sure that FIRST_USER_EMAIL and FIRST_USER_PASSWORD are NOT defined in the .env file. Also leave the DB_PASSWORD and SECRET with new generated values.
  8. Start fresh SUPLA app. It can take a few minutes to settle down. 
    ./supla-docker/supla.sh start
  9. Make sure it works, i.e. you can visit the SUPLA Cloud homepage and the services claim they are running with docker ps.
  10. Copy and restore the database backup. Replace the *** below with actual dump filename.
cp supla-docker-old/var/backups/supla***.sql.gz supla-docker/var/backups/supla_backup_2025.sql.gz
gunzip supla-docker/var/backups/supla_backup_2025.sql.gz
cd supla-docker
source .env
cat var/backups/supla_backup_2025.sql | docker compose exec -T supla-db mariadb -u supla --password="${DB_PASSWORD}" supla
  1. Restart the application.
./supla-docker/supla.sh restart
  1. Enter the application. Make sure that everything works. Try to connect with phone and switch some device etc.
  2. Delete the old supla-docker-old directory.
rm -fr supla-docker-old

Clone this wiki locally