Upgrading to OpenCloud 4.0.0

This guide explains how to upgrade from the previous stable opencloud_full Compose setup to the new opencloud-compose repository structure.
It covers both types of persistent storage used in earlier deployments:

• Bind mounts: host directories mapped into containers.
• Docker named volumes: volumes managed directly by Docker.

Following this guide, you can safely migrate to the stable v4.0.0 release of OpenCloud.

Before You Begin

• Determine Your Deployment Type: This guide covers two common setups:
  • Bind Mounts: Config and data are stored in directories on the host machine (e.g., /mnt/opencloud/config).
  • Docker Named Volumes: Config and data are managed by Docker. You will need your COMPOSE_PROJECT_NAME to access them.
• Check Paths: If you are using bind mounts, ensure you know the correct paths on your host system. You can find them by inspecting your current container's docker run command or docker-compose.yml file (look for volumes: sections that map to host paths). For a running container, docker inspect opencloud_full-opencloud-1 also exposes this information in the Mounts section.

Backup Config and Data

important

Important: Always create a backup before upgrading to prevent data loss.
We strongly recommend following the backup documentation and creating copies of your configuration and data directories.

Using Bind Mounts

If your config and data are stored in host directories (bind mounts), create a direct copy of these folders.

Example (adjust paths to match your setup)

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

Using Named Volumes

Create backup directory

mkdir -p ~/opencloud-backups

Backup config and data

docker cp opencloud_full-opencloud-1:/var/lib/opencloud ~/opencloud-backups/data-backup
docker cp opencloud_full-opencloud-1:/etc/opencloud ~/opencloud-backups/config-backup

Stop OpenCloud

First, gracefully stop your currently running OpenCloud instance:

docker

docker stop opencloud

docker compose

docker compose stop

Pull the 4.0.0 Production Release Image

docker pull opencloudeu/opencloud:4.0.0

Update Deployment Configuration

docker compose

Clone the opencloud-compose Repository

Clone the official opencloud-compose repository onto your server:

git clone https://github.com/opencloud-eu/opencloud-compose.git
cd opencloud-compose

Migrate Environment Variables

Transfer your existing environment variables to the new opencloud-compose structure. Refer to the Docker Compose configuration documentation for detailed instructions.

Verify Configuration Changes

Go inside the container:

If your config is stored in host directories (change <your-home-directory> to your home directory. In our example it is /mnt ):

docker run --rm -it --entrypoint /bin/sh -v <your-home-directory>/opencloud/opencloud-config:/etc/opencloud opencloudeu/opencloud:4.0.0

or, if you use Docker Named Volumes (replace <your-named-volume>with your volume name. In our example it is opencloud_full_opencloud-config):

docker run --rm -it --entrypoint /bin/sh \
  -v <your-named-volume>:/etc/opencloud \
  opencloudeu/opencloud:4.0.0

Check for configuration changes:

opencloud init --diff

Example output:

opencloud init --diff
Do you want to configure OpenCloud with certificate checking disabled?
 This is not recommended for public instances! [yes | no = default] yes
running in diff mode
diff -u /etc/opencloud/opencloud.yaml /etc/opencloud/opencloud.yaml.tmp
--- /etc/opencloud/opencloud.yaml
+++ /etc/opencloud/opencloud.yaml.tmp
@@ -3,6 +3,7 @@
 machine_auth_api_key: k55Y7i3Djeeu4aPPNzM67Q39rf3ZHz^9
 system_user_api_key: GeTXN@Mj7-4n8Yhuwb&#oq8Gb1hF7Q%^
 transfer_secret: ANy#T5.IvknED9-Ud39+YmlXzN^TdaKi
+url_signing_secret: zB#FtAYid24Z^DkuBoTllnId=igo!tCO
 system_user_id: 8cc36d34-cd87-4434-b9e2-726e5553609c
 admin_user_id: 34a73600-a02c-4064-8aec-341cd1865a71
 graph:

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

Apply any necessary changes to /etc/opencloud/opencloud.yaml based on the diff output. In this example, add url_signing_secret to your opencloud.yaml.

Start OpenCloud (v4.0.0)

docker

docker run \
    --name opencloud \
    --rm \
    -d \
    -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:4.0.0

docker compose

Important Note for Existing Deployments

If you previously deployed OpenCloud using the project name opencloud_full (our earlier example) and are now switching to the official opencloud-compose repository, you may need to specify the original project name to ensure:

• Network compatibility - for services like S3 that need to be on the same network
• Volume persistence - to access existing Docker volumes

Run the command with your original project name:

docker compose -p opencloud_full up -d

Alternatively, set the project name permanently in the .env file:

COMPOSE_PROJECT_NAME=opencloud_full

Then use the standard command:

docker compose up -d

Verification

Your OpenCloud instance should now be running on v4.0.0.

Essential Checks

• User Accounts — Confirm all users can log in successfully
• Shared Folders — Verify shared folder permissions and access
• Public Links — Test that public links remain functional
• Data Integrity — Ensure all files and folders are accessible
• Service Health — Check logs for any errors or warnings

Troubleshooting

If you encounter issues during or after the upgrade:

1. Review the logs for error messages
2. Consult the troubleshooting guide
3. Restore from backup if necessary
4. Contact support or open an issue on GitHub