Files and storage, checked 2026-09-07
Nextcloud: Docker configuration reference
Self-hosted file sync, share and collaboration platform with calendar, contacts and mail apps.
At a glance
- Image:
docker.io/library/nextcloud - Tags:
34.0.3-apache,34.0.3-fpm,stable-apache,production-apache,latest - Licence: AGPL-3.0
- Source: https://github.com/nextcloud/server
- Docs: https://docs.nextcloud.com/server/latest/admin_manual/
Ports
| Port | What listens | Source |
|---|---|---|
80 | HTTP listener on the apache variant, which is the default for the latest and unqualified version tags. | source for port 80 |
9000 | FastCGI port exposed by the fpm variant. Needs a separate webserver in front to serve static assets and proxy PHP requests here; do not map it to the host. | source for port 9000 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
TRUSTED_PROXIES | No | Space-separated list of reverse proxy addresses to trust for X-Forwarded-* headers. CIDR is supported for IPv4. Used together with APACHE_DISABLE_REWRITE_IP. | 172.18.0.0/16 | source for TRUSTED_PROXIES |
APACHE_DISABLE_REWRITE_IP | No | Disables the apache image's default rewrite of the remote address from X-Real-IP for proxies in the private IP ranges. Needed to pick up X-Forwarded-Host/Proto/For instead. | 1 | source for APACHE_DISABLE_REWRITE_IP |
OVERWRITEPROTOCOL | No | Forces config.php's overwriteprotocol when automatic scheme detection behind the proxy is wrong, which otherwise generates http links behind a TLS-terminating proxy. | https | source for OVERWRITEPROTOCOL |
NEXTCLOUD_TRUSTED_DOMAINS | No | Space-separated list of hostnames added to trusted_domains after install. Requests to an untrusted domain are rejected. | cloud.example.com | source for NEXTCLOUD_TRUSTED_DOMAINS |
POSTGRES_HOST | No | Together with POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD, auto-configures the database on first run and skips the setup wizard's database step. All four must be set or none are used. | db | source for POSTGRES_HOST |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/var/www/html | Main install directory. Files here are overwritten on upgrade except paths listed in upgrade.exclude, so config, data, custom_apps and themes should be mounted as their own volumes. | source for /var/www/html |
/var/www/html/data | User file data. Overridable with NEXTCLOUD_DATA_DIR. | source for /var/www/html/data |
/var/lib/postgresql/data (db) | Database volume when using the PostgreSQL auto-configuration path. | source for /var/lib/postgresql/data |
Behind a reverse proxy
- Set trusted_proxies to the proxy's address and forwarded_for_headers if it is not the de-facto X-Forwarded-For, or Nextcloud logs and rate-limits the proxy's IP instead of the client's. source for this reverse-proxy note
- If hostname, protocol or webroot detection fails behind the proxy, set overwritehost, overwriteprotocol and overwritewebroot in config.php explicitly rather than relying on auto-detection. source for this reverse-proxy note
- CalDAV/CardDAV redirects for /.well-known/carddav and /.well-known/caldav do not work automatically behind a proxy; the proxy itself needs to issue the 301 to /remote.php/dav/. source for this reverse-proxy note
- This image is maintained by community volunteers for expert use; the Nextcloud All-in-One container is the officially supported path for a simpler deployment. source for this reverse-proxy note
What it needs alongside it
| Dependency | Why | Source |
|---|---|---|
| MySQL/MariaDB or PostgreSQL (SQLite for testing only) | Auto-configured via matching sets of MYSQL_* or POSTGRES_* environment variables; only one database type should be configured at a time. | source for MySQL/MariaDB or PostgreSQL (SQLite for testing only) |
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v34.0.3 | 2026-08-13 | No | Point release on the 34.0 line, published together with matching point releases for the 33.0 and 32.0 supported lines. | source for release v34.0.3 |
v34.0.2 | 2026-07-23 | No | Point release on the 34.0 line. | source for release v34.0.2 |
v34.0.1 | 2026-06-25 | No | Point release on the 34.0 line. | source for release v34.0.1 |
If it is not coming up
- 502 Bad Gateway (Traefik) — build succeeds and container runs, but your-domain.com returns 502 Bad Gateway
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
- Gate a self-hosted app with Cloudflare Access
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.