Standard Upgrade Guide

This guide provides the standard steps to upgrade OpenCloud for both docker and docker compose

Stop OpenCloud

Stop the currently running OpenCloud instance:

docker

docker stop opencloud

docker compose

docker compose stop

Back Up Configuration and Data

Using Bind Mounts

If your configuration and data are stored in directories on the host, create a copy of these directories.

Example:

cp -a /mnt/opencloud/config /mnt/opencloud/config-backup
cp -a /mnt/opencloud/data /mnt/opencloud/data-backup

Replace the paths with the directories used by your deployment.

Using Named Volumes

Create a backup directory and copy the configuration and data from the OpenCloud container.

mkdir -p ~/opencloud-backups
docker cp opencloud-compose-opencloud-1:/etc/opencloud ~/opencloud-backups/config-backup
docker cp opencloud-compose-opencloud-1:/var/lib/opencloud ~/opencloud-backups/data-backup

Replace opencloud-compose-opencloud-1 with the name of your OpenCloud container if it differs.

Update the opencloud-compose Checkout

If you use the opencloud-compose repository, update your local copy of the repository.

cd /opencloud-compose
git pull

Skip this step if you run OpenCloud with plain Docker.

Stop OpenCloud

Stop the currently running OpenCloud instance.

Docker Compose

docker compose stop

Docker

docker stop opencloud

Pull the new OpenCloud image

Pull the image that matches the release channel you use:

• opencloudeu/opencloud-rolling:{tag} for rolling releases
• opencloudeu/opencloud:{tag} for stable releases

Replace {tag} with the image tag for the version you want to install. Available tags are listed on Docker Hub.

docker pull opencloudeu/opencloud-rolling:{tag}

Verify Configuration Changes

If upgrading from an older release, check for required configuration changes:

Open a Temporary OpenCloud Container

Open a shell in a temporary OpenCloud container and mount your OpenCloud configuration directory or configuration volume to /etc/opencloud.

Using Named Volumes

docker run --rm -it --entrypoint /bin/sh -v "<opencloud-config-volume>:/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag"

Replace <opencloud-config-volume> with the Docker volume or bind mount that contains your OpenCloud configuration.

Using Bind Mounts

docker run --rm -it --entrypoint /bin/sh -v "<path-to-your-config-directory>:/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag"

Replace <path-to-your-config-directory> with the host directory that contains your opencloud.yaml.

Generate the Configuration Diff

Inside the temporary container, run:

opencloud init --diff

If you see no changes, your config is up to date, no further action is needed.

In that case, exit the temporary container and start OpenCloud.

Otherwise, update your opencloud.yaml file accordingly and apply the patch.

Example output:

diff -u /etc/opencloud/opencloud.yaml /etc/opencloud/opencloud.yaml.tmp
--- /etc/opencloud/opencloud.yaml
+++ /etc/opencloud/opencloud.yaml.tmp
@@ -90,6 +90,9 @@
 sharing:
   events:
     tls_insecure: false
+service_account:
+  service_account_id: 00000000-0000-0000-0000-000000000000
+  service_account_secret: example-service-account-secret
 storage_users:
   events:
     tls_insecure: false

diff written to /etc/opencloud/opencloud.config.patch

The command creates the following patch file:

/etc/opencloud/opencloud.config.patch

Apply the Configuration Patch

Change to the configuration directory:

cd /etc/opencloud

Verify that the patch file was created:

ls

Example output:

banned-password-list.txt
csp.yaml
opencloud.config.patch
opencloud.yaml
opencloud.yaml.2026-05-19-15-45-44.backup

Test the patch before applying it:

patch --dry-run opencloud.yaml < opencloud.config.patch

Expected output:

checking file opencloud.yaml

Apply the patch:

patch opencloud.yaml < opencloud.config.patch

Expected output:

patching file opencloud.yaml

Verify that the following configuration entries exist in opencloud.yaml:

service_account:
  service_account_id: 00000000-0000-0000-0000-000000000000
  service_account_secret: example-service-account-secret

Exit the Temporary Container

Exit the temporary container after applying the configuration patch.

exit

Start OpenCloud with updated image

docker

docker run \
--name opencloud \
--rm \
-it \
-p 9200:9200 \
-v $HOME/opencloud/opencloud-config:/etc/opencloud \
-v $HOME/opencloud/opencloud-data:/var/lib/opencloud \
-e OC_INSECURE=true \
-e PROXY_HTTP_ADDR=0.0.0.0:9200 \
-e OC_URL=https://localhost:9200 \
opencloudeu/opencloud-rolling:{tag}

docker compose

docker compose up -d

Conclusion

Make sure that all previously created data, users, shared files, public links exist.