How to Update Nextcloud Docker: A Step-by-Step Guide for 2026

Introduction

Running Nextcloud in Docker gives you portability and easy rollbacks, but updating it incorrectly can lead to data loss or a broken instance. The official Nextcloud image is updated frequently, and as of August 2026, the latest stable release is v34.0.3. This guide walks you through a safe, step-by-step upgrade process using Docker Compose, covering everything from pre-update checks to post-update verification.

You will learn how to:

• Prepare your environment and back up your data.
• Update the image version and apply database migrations.
• Handle common post-update issues like permission errors and caching problems.
• Implement advanced practices like reverse proxy and automated backups.

By the end, you'll have a repeatable, reliable update routine that minimises downtime and risk.

Prerequisites

Before you start, ensure your host meets the following requirements. These are typical values; actual usage depends on your number of users and files.

Software you need: Docker Engine and Docker Compose plugin. Verify with docker --version and docker compose version. Also, ensure curl and jq are installed for some commands.

Step-by-Step Update Process

Step 1: Create a Project Directory and .env File

If you don't have a dedicated directory, create one and move your existing docker-compose.yml there. Then create a .env file to store secrets and version variables.

mkdir -p ~/nextcloud && cd ~/nextcloud && touch .env

Edit .env with nano .env and add the following content. Never commit this file to Git – it contains secrets.

NEXTCLOUD_VERSION=34.0.3
MYSQL_PASSWORD=change_this_strong_password
MYSQL_ROOT_PASSWORD=change_this_root_password
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=change_this_admin_password

Set strict permissions: chmod 600 .env.

Step 2: Back Up Your Current Instance

Before any update, back up your Nextcloud data, database, and configuration. This is non-negotiable.

# Assuming containers are running
docker exec -u www-data nextcloud php occ maintenance:mode --on

# Backup config and data directories (adjust paths if needed)
tar -czf nextcloud-backup-$(date +%Y%m%d).tar.gz ./data ./config

# Backup database (example for MySQL)
docker exec nextcloud-db sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > db-backup-$(date +%Y%m%d).sql

# Disable maintenance mode after backup
docker exec -u www-data nextcloud php occ maintenance:mode --off

Store backups in a separate location, not on the same disk.

Step 3: Pull the Latest Image and Compare Versions

Your docker-compose.yml should reference the version via environment variable. If you haven't, update it now. Below is a complete example.

version: '3.8'

services:
  nextcloud:
    image: nextcloud:${NEXTCLOUD_VERSION:-latest}
    container_name: nextcloud
    restart: unless-stopped
    ports:
      - "8080:80"
    depends_on:
      - db
    environment:
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - NEXTCLOUD_ADMIN_USER=${NEXTCLOUD_ADMIN_USER}
      - NEXTCLOUD_ADMIN_PASSWORD=${NEXTCLOUD_ADMIN_PASSWORD}
    volumes:
      - ./data:/var/www/html/data
      - ./config:/var/www/html/config
      - ./apps:/var/www/html/apps
      - ./theme:/var/www/html/themes
    networks:
      - nextcloud-net

  db:
    image: mariadb:10.11
    container_name: nextcloud-db
    restart: unless-stopped
    command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
    volumes:
      - ./db:/var/lib/mysql
    networks:
      - nextcloud-net

networks:
  nextcloud-net:
    driver: bridge

Note: The above uses latest as fallback, but you should pin to a specific version for production. Check the official Nextcloud Docker tags before pinning; the version above may be outdated by now.

Now pull the new image:

docker compose pull nextcloud

Step 4: Update the Image Version in .env

If you're going to a specific new version, change NEXTCLOUD_VERSION in .env. For this guide, we'll set it to 34.0.3.

sed -i 's/^NEXTCLOUD_VERSION=.*/NEXTCLOUD_VERSION=34.0.3/' .env

Step 5: Recreate the Container with the New Image

Run the following to apply changes:

docker compose up -d

This will recreate the Nextcloud container with the new image. The database container remains unchanged.

Step 6: Run Database Migrations and Upgrade Routine

After the container starts, you need to run the upgrade routine. The official image usually runs it automatically on startup, but it's safer to do it manually.

docker exec -u www-data nextcloud php occ upgrade

If the automatic upgrade fails, check logs with docker logs nextcloud.

Step 7: Verify the Upgrade

Check the version and status:

docker exec -u www-data nextcloud php occ status

You should see version 34.0.3. Also, visit your Nextcloud web UI to ensure it loads correctly.

Step 8: Post-Update Cleanup

Clear any caches and rebuild assets if needed:

docker exec -u www-data nextcloud php occ maintenance:repair

Also, remove old images to free space:

docker image prune -f

Step 9: Update the Database Container (Optional)

If you also want to update MariaDB, do it separately. First, back up the database, then change the image tag in docker-compose.yml, and run docker compose up -d db. Follow the same backup and verification steps.

Step 10: Test Your Setup Thoroughly

Log in, create a test file, sync with a client, and check that all apps work. This ensures nothing is broken.

Advanced Setup and Hardening

Reverse Proxy with SSL

For production, use a reverse proxy like Nginx or Traefik to handle HTTPS. Below is a minimal Nginx example using Let's Encrypt.

server {
    listen 443 ssl http2;
    server_name cloud.example.com;

    ssl_certificate /etc/letsencrypt/live/cloud.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cloud.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Backups Automation

Use a cron job to automate backups. Example script:

#!/bin/bash
cd ~/nextcloud
# Maintenance mode on, backup, off (as in Step 2)
# Then rotate backups older than 7 days
find ~/backups -name "*.tar.gz" -mtime +7 -delete

Add to crontab: 0 2 * * * /home/user/backup.sh.

Optional Hardening

Warning: The following settings are advanced and may break your setup if copied blindly. Test in a staging environment first.

• Run containers with read-only root filesystem: Add read_only: true to the Nextcloud service. This prevents writes to the container's filesystem, but you must ensure all writable paths are mounted as volumes. Nextcloud needs /var/www/html/data, /var/www/html/config, /var/www/html/apps, and /tmp writable. Add a tmpfs for /tmp.
• Drop Linux capabilities: Add cap_drop: - ALL and then selectively add back needed ones like cap_net_bind_service if using port 80 directly (but with reverse proxy, not needed).
• Use non-root user: The image runs as www-data (UID 33). On the host, create a user with that UID and set ownership of volumes accordingly. Verify with id -u www-data inside the container.

These changes require careful volume mapping and may require adjustments to your specific setup.

Troubleshooting Common Errors

Conclusion

Updating Nextcloud in Docker doesn't have to be scary. By following a systematic process—backup, image update, migration, and verification—you can keep your instance secure and feature-rich. Always pin your image version, maintain regular backups, and test in a staging environment if possible.

For further reading, consult the official Nextcloud admin manual and the Docker image documentation.

FAQ

1. Can I skip multiple versions when updating?

Yes, but it's riskier. Nextcloud supports upgrades from the last two major versions. If you're more than one major version behind, you must upgrade stepwise. For example, from 30 to 34, you'd need to go to 31, 32, 33, then 34. Always read the release notes for major upgrades.

2. How often should I update Nextcloud?

Minor updates (e.g., 34.0.1 to 34.0.2) can be done monthly. Major updates (e.g., 34 to 35) should be planned, as they may require more attention. Subscribe to the Nextcloud release feed to stay informed.

3. What if my update fails and I can't access my instance?

Restore from your backup. Since you backed up before the update, you can revert to the previous image by changing the version in .env and running docker compose up -d. Then restore the database and data directories.

4. Do I need to update the database container too?

Not always. Nextcloud supports MariaDB 10.6 and later. If your database version is still supported, you can keep it. If you're using an old version, consider updating it separately after a backup.

5. How can I automate the update process?

You can write a script that does the backup, pulls the new image, recreates the container, and runs occ upgrade. Use cron to run it monthly. But always have a manual review step for major updates.