docker-compose-cookbooks/nextcloud/README.md

nextcloud

Overview

Self-hosted file sync, sharing, and collaboration platform. This stack runs Nextcloud (Apache) with MariaDB, Redis for caching and file locking, and a cron container for background jobs.

Project Details

• Project Repository: GitHub
• Container Image: nextcloud, mariadb, redis
• Documentation: Admin Manual
• Reverse Proxy Port: 80

Getting Started

1. Set NEXTCLOUD_DOMAIN and change every ChangeThisPassword in sample.env
2. Start the stack: docker compose up -d
3. In NPM, add a proxy host for NEXTCLOUD_DOMAIN → http://nextcloud:80 with SSL enabled
4. Open https://NEXTCLOUD_DOMAIN and create the admin account (the database fields are pre-filled from the environment)

To test without NPM, open http://HOST_IP:8084. Set NEXTCLOUD_DOMAIN=HOST_IP and NEXTCLOUD_OVERWRITEPROTOCOL=http first. Otherwise Nextcloud rejects the untrusted domain and redirects you to https links that don't work.

Environment Variable Notes

NEXTCLOUD_IMAGE – default: nextcloud:35 (pin the major version, see Gotchas)
MARIADB_IMAGE – default: mariadb:11.8 (the version Nextcloud recommends)
REDIS_IMAGE – default: redis:alpine
NEXTCLOUD_DB – default: nextcloud
NEXTCLOUD_DB_USER – default: nextcloud
NEXTCLOUD_DB_PASSWORD – default: ChangeThisPassword
NEXTCLOUD_DB_HOST – default: nextcloud-db
MARIADB_ROOT_PASSWORD – default: ChangeThisPassword
NEXTCLOUD_REDIS_HOST – default: nextcloud-redis
NEXTCLOUD_DOMAIN – public hostname without a scheme; sets trusted_domains (first install only) and overwrite.cli.url
NEXTCLOUD_TRUSTED_PROXIES – default: 172.16.0.0/12 (Docker bridge range, covers NPM)
NEXTCLOUD_PORT – default: 8084; host port for testing without NPM (NPM connects to nextcloud:80)
NEXTCLOUD_OVERWRITEPROTOCOL – default: https; generates https links behind NPM's TLS termination
VOL_CACHE – default: /var/cache; base path for regenerable data (exclude from backups)

Volume Notes

/var/lib/mysql – host path /data/nextcloud/db (MariaDB data)
/data – host path /var/cache/nextcloud/redis (Redis cache, file locks and sessions; safe to lose, users are logged out)
/var/www/html – host path /data/nextcloud/data (Nextcloud app, config and user files; shared by nextcloud and nextcloud-cron)

Back up /data/nextcloud/data and /data/nextcloud/db together. Leave out /var/cache, because Redis rebuilds its cache.

To keep backups small, exclude data/data/appdata_* (thumbnail previews and generated JS/CSS, often several GB). Nextcloud regenerates these on demand. It also holds a few things that aren't regenerated, such as theming uploads and the federation signing keys. If you rely on those, exclude only data/data/appdata_*/preview.

rsync -a --exclude '/data/appdata_*' /data/nextcloud/data/ /backup/nextcloud/data/

Network Notes

Requires proxy network. nextcloud joins proxy and internal; nextcloud-db, nextcloud-redis and nextcloud-cron join internal only.

Docker Run

Nextcloud needs the database container to run, so use compose. The app container alone looks like this:

docker run -d \
  --name nextcloud \
  --network proxy \
  -p 8084:80 \
  -e MYSQL_HOST=nextcloud-db \
  -e MYSQL_DATABASE=nextcloud \
  -e MYSQL_USER=nextcloud \
  -e MYSQL_PASSWORD=ChangeThisPassword \
  -v /data/nextcloud/data:/var/www/html \
  nextcloud:35

See compose.yaml for the full set of services and environment variables.

Additional Notes / Gotchas

• Upgrade one major version at a time. Nextcloud can't skip majors (for example 33 → 35 fails). Bump NEXTCLOUD_IMAGE step by step and let each version finish its upgrade before moving on.
• MariaDB can't be downgraded. If an existing install has already run a newer mariadb:latest, keep MARIADB_IMAGE at that version. Data files from a newer MariaDB won't start on 11.8. MARIADB_AUTO_UPGRADE=1 handles upgrades.
• Env vars that only apply on first install: NEXTCLOUD_TRUSTED_DOMAINS and the database settings. For an existing install, set the domain with occ: docker compose exec -u www-data nextcloud php occ config:system:set trusted_domains 1 --value=cloud.example.com
• Background jobs: after install, go to Administration settings → Basic settings and select Cron. The nextcloud-cron container runs cron.php every 5 minutes.
• NPM: increase the upload limit in the proxy host's Advanced tab (for example client_max_body_size 10G;) or large uploads will fail.
• Nextcloud All-in-One: compose-aio.yaml is an alternative to this stack, not an add-on. The master container spawns and manages its own containers, so container and volume names are fixed. It doesn't join the proxy network. Open the AIO admin UI at https://HOST:8080, then point NPM at http://HOST_IP:11000 (the APACHE_PORT). User data goes to /data/nextcloud-aio.

Useful commands

docker compose exec -u www-data nextcloud php occ status
docker compose exec -u www-data nextcloud php occ app:list
docker compose exec -u www-data nextcloud php occ app:disable <appname>
docker compose exec -u www-data nextcloud php occ maintenance:mode --on
docker compose exec -u www-data nextcloud php occ trashbin:cleanup --all-users
docker compose exec -u www-data nextcloud php occ db:add-missing-indices

Dockhand Stack, Deploy from Git

Cookbooks Repository stackname: nextcloud Compose file path: nextcloud/compose.yaml Additional env file (optional): nextcloud/sample.env

Then "Load" nextcloud/sample.env into the Environmental variables in dockhand

Create the Stack