Submit

File Storage guide

Nextcloud Docker Compose Setup: A Maintainable Small-Team Stack

Deploy Nextcloud with a separate database, persistent volumes, HTTPS, trusted proxies, background jobs, and a maintenance plan.

Published and reviewed by OpenAlt · September 22, 2026

Detailed view of a server rack with a focus on technology and data storage.
Photo by panumas nikhomkhai on Pexels

Nextcloud Docker Compose is a practical small-team replacement for hosted file sync when you separate the application from its database, persist every important volume, terminate HTTPS at a reverse proxy, and schedule maintenance from the beginning. The result is easier to update, back up, troubleshoot, and move than an improvised single-container installation.

Table of Contents

Choose architecture

A small team should use Nextcloud with a separate database, persistent application data, Redis where appropriate, and HTTPS in front of the stack. This keeps operational responsibilities visible instead of hiding them inside a fragile all-in-one container.

The basic layout is:

  • Nextcloud application container
  • Supported database service
  • Redis service for transactional file locking and related caching needs
  • Named volumes or carefully managed bind mounts
  • Reverse proxy handling public HTTPS
  • Scheduled background jobs
  • Backup storage outside the live data path

The official Nextcloud Docker image README provides Compose examples. Adapt paths, secrets, networking, and proxy details to your host.

Preflight

Before deployment, confirm that the host, storage, DNS, and recovery plan are ready.

Use this compact checklist:

  • Linux host or NAS with Docker Engine and Compose support
  • Enough storage for current files, growth, database data, and backups
  • Stable hostname pointing to the reverse proxy
  • HTTPS certificate process understood before users are invited
  • Separate backup destination, preferably on another disk or system
  • Firewall rules limited to required services
  • Credentials kept outside version control

Check the host against the official Nextcloud system requirements. The important operational question is not only whether the first launch works, but whether the host has enough resources and supported components for routine upgrades and file indexing.

Build the stack

A maintainable Compose deployment gives each stateful component a persistent location. Container recreation is not a backup strategy.

App, database, Redis, and volumes

The application serves Nextcloud, the database stores structured records, and Redis supports locking and caching. Persistent volumes survive recreation but not disk failure or operator error.

Use the official Docker image documentation to choose the supported image pattern and Compose structure. Keep the application, database, and Redis on an internal Compose network unless a specific deployment requires otherwise.

Keep application configuration, user data, database data, and backup storage distinct. The database needs a database-aware backup; uploaded files need a consistent copy; Redis is not file storage; and the reverse proxy must forward the headers Nextcloud expects.

First launch

The first launch should establish the database, persistent paths, administrator account, and trusted hostname before users begin syncing.

Use this workflow:

  1. Create the Compose project directory with restricted access.
  2. Define persistent storage for application configuration, user data, database data, and Redis.
  3. Store database credentials and secrets using the deployment environment’s protected mechanism.
  4. Start the stack, open the intended HTTPS hostname, and complete setup with the separate database.
  5. Create one test account and record volume names, service names, and recovery steps.

Useful first checks include:

docker compose ps
docker compose logs --tail=100 nextcloud
docker compose logs --tail=100 db
docker compose exec nextcloud php occ status

If your service names differ, adjust the commands. Verify database reachability, stable containers, and an initialized application—not merely a responding web page.

HTTPS and proxy trust

HTTPS and correct reverse-proxy trust settings are required for a reliable public deployment. Configure the proxy and Nextcloud together so generated links, login redirects, WebDAV URLs, and secure-cookie behavior all agree on the external scheme and hostname.

The official reverse proxy guidance explains the settings that matter when Nextcloud is behind another web server. Pay particular attention to:

  • The public hostname users actually enter
  • Whether the proxy terminates TLS before forwarding traffic
  • Forwarded host and protocol headers
  • Trusted proxy addresses
  • Any path prefix, if Nextcloud is not served at the domain root
  • WebSocket or long-request behavior required by your proxy arrangement

In a private window, test login, file upload, sharing links, and WebDAV. The browser must stay on HTTPS and generated links must use the public hostname. A working login page alone does not prove uploads or redirects work.

Detailed image of illuminated server racks showcasing modern technology infrastructure.
Photo by panumas nikhomkhai on Pexels
An IT professional operates a computer in a server room, managing network systems and connected devices.
Photo by panumas nikhomkhai on Pexels

Cron and background jobs

Use cron for routine background jobs when the server can schedule them reliably. AJAX-triggered jobs depend on user activity and are a poor fit for a small team that expects predictable maintenance and notifications.

In Nextcloud administration, select the cron method and then arrange for the relevant occ background-job command to run from the host or a dedicated scheduler container, following the deployment pattern you chose. Confirm that jobs run without permission errors and that the last-run time advances.

Confirm the cron command runs as the correct account, can access application data, advances its last-run time, survives restart, and produces no repeated locking or permission failures. File scanning, notifications, cleanup, and previews should not depend on someone opening the web interface.

Verify sync and WebDAV

Verify the complete user path: browser login, desktop sync, mobile access if needed, sharing, and WebDAV. A green container status proves only that processes are running; it does not prove that clients can safely read and write files.

Run these checks:

  1. Upload a small test file through the web interface.
  2. Download and rename it through the browser.
  3. Connect one desktop client and confirm two-way synchronization.
  4. Create a shared folder and verify permissions.
  5. Test WebDAV through the HTTPS hostname.
  6. Inspect administration warnings and recent application/proxy logs.

Use docker compose ps, docker compose logs --tail=100 nextcloud, and php occ status for command-line checks. Keep the test account through the first restore exercise.

Backup, update, and rollback

Back up the database, configuration, and user data together, and keep the backup destination separate from the live Compose project. The official backup guidance should define your backup design, especially the need for a consistent database backup and a recoverable copy of Nextcloud’s important files.

Your maintenance cycle should be:

  1. Announce a maintenance window.
  2. Confirm the latest backup is readable and record current image references.
  3. Pull updates and recreate services with the documented workflow.
  4. Run required occ maintenance or upgrade tasks.
  5. Check logs, cron, sync, sharing, and WebDAV.
  6. Keep the previous known-good image until verification finishes.

If the update fails, stop user access, preserve logs, and return to the documented image and configuration only after confirming database compatibility. Test rollback before an emergency.

Common failures

Diagnose lost persistence, proxy trust, database connectivity, permissions, and recovery by layer instead of restarting every container.

  • Files disappear after recreation: the user-data path is not persistent or the wrong volume is mounted.
  • The setup page returns after restart: configuration was not preserved, or the application is pointed at a new empty volume.
  • Login redirects or insecure links appear: external HTTPS and forwarded headers are not represented correctly.
  • Uploads fail while browsing works: inspect proxy request limits, timeouts, and the application logs.
  • Database connection errors appear: verify the Compose service name, credentials, network, and database readiness.
  • Sync loops or locking warnings occur: check Redis availability, file ownership, and client logs.
  • Jobs never finish: confirm cron is actually running and has permission to execute the application command.
  • An update behaves badly: preserve logs, stop further changes, and use the documented backup and rollback procedure.

For a focused deployment path, review Nextcloud on OpenAlt, compare related options in the file-storage directory, and estimate the financial tradeoff with the self-host savings calculator.

Frequently Asked Questions

SQLite or database server?

Use a separate database server for a small team expected to rely on Nextcloud regularly. SQLite can simplify an evaluation or very small single-user installation, but a dedicated database service gives the production stack a clearer upgrade, backup, and scaling boundary. Check the official system requirements before choosing.

Is Redis required?

Redis is recommended when the deployment needs reliable transactional file locking and caching support. It is an additional service to operate, but omitting it can create avoidable contention and locking problems as simultaneous access increases. Follow the supported pattern in the official Docker documentation.

Which folders/data must be backed up?

Back up the Nextcloud configuration, user data, and database using a consistent procedure. Also preserve the Compose project’s deployment details, secrets-recovery process, and any custom proxy configuration needed to rebuild the service. The official backup guidance is the source of truth for the backup scope.

Can it run on a NAS?

Yes, if the NAS supports a compatible Docker and Compose environment, persistent storage, scheduled jobs, HTTPS routing, and a backup destination that is separate from the live data. Verify the NAS against Nextcloud’s system requirements and test restoration before moving team files.