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](https://github.com/nextcloud/docker)
-   **Container Image:** [nextcloud](https://hub.docker.com/_/nextcloud), [mariadb](https://hub.docker.com/_/mariadb), [redis](https://hub.docker.com/_/redis)
-   **Documentation:** [Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/)
-   **Reverse Proxy Port:** `80`

## Getting Started

1. Set `NEXTCLOUD_DOMAIN` and change every `ChangeThisPassword` in `sample.env`
2. Copy the MariaDB tuning file to the data directory **before the first start**. If it's missing, Docker creates a directory at that path and `nextcloud-db` fails to start:
   ```bash
   mkdir -p /data/nextcloud/db-conf
   cp config/nextcloud-tuning.cnf /data/nextcloud/db-conf/
   ```
3. Start the stack: `docker compose up -d`
4. In NPM, add a proxy host for `NEXTCLOUD_DOMAIN` → `http://nextcloud:80` with SSL enabled
5. 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)
    /etc/mysql/conf.d/nextcloud-tuning.cnf – host path /data/nextcloud/db-conf/nextcloud-tuning.cnf (read-only MariaDB tuning; copy from config/ in this repo, restart nextcloud-db after edits)
    /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`.

```bash
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:

```bash
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

```bash
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