You’re probably here because you’re tired of paying for Google Drive or Dropbox — or because you don’t love the idea of your files living on someone else’s server. Nextcloud is the answer: a self-hosted file sync, calendar, and contacts platform that runs on hardware you own.

This guide walks you through self-hosting Nextcloud with Docker in under 30 minutes, including the exact config files, common pitfalls, and what to do after you’re up and running.

Don’t have a server yet? Start with our homelab setup guide first.

What you need

  • A server with Docker and Docker Compose installed. Any mini PC, VPS, or even a Raspberry Pi works.
  • A domain name pointing to your server. You need this for HTTPS, which is essential for a service that handles your files.
  • About 15–30 minutes of focused time.

Why Docker (and not a bare-metal install)?

Docker makes Nextcloud reproducible. Your entire setup — the app, the database, and the storage — lives in one compose file. If your server dies, you restore the file and the volumes, and you’re back in minutes. A bare-metal install is harder to migrate, harder to update, and much harder to undo if something goes wrong.

The tradeoff is a small learning curve, but the payoff is worth it: you’ll use the same skills for every other self-hosted app.

Step 1: Create the Docker Compose file

Create a folder for Nextcloud and add a docker-compose.yml:

services:
  db:
    image: mariadb:11
    container_name: nextcloud_db
    restart: always
    command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
    volumes:
      - db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ***
      MYSQL_PASSWORD: ***
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud

  app:
    image: nextcloud:stable
    container_name: nextcloud_app
    restart: always
    ports:
      - "8080:80"
    depends_on:
      - db
    volumes:
      - nextcloud:/var/www/html

volumes:
  db:
  nextcloud:

A few things to notice:

  • Two services. The database (MariaDB) and the Nextcloud app run as separate containers. This separation is cleaner than stuffing everything into one image.
  • Replace the two *** passwords with strong, unique ones. These are your only keys to the database.
  • Named volumes (db and nextcloud) persist your data across container restarts and updates.

Step 2: Start it

docker compose up -d

The -d flag runs it in the background. On first start, MariaDB initializes the database — give it 30 seconds or so.

Open http://your-server-ip:8080 and complete the setup form. Use nextcloud for the database user, database name, and the password you set in the compose file. Leave the database host as db — that’s the Docker service name, not an IP address.

Step 3: Put it behind HTTPS

Nextcloud stores sensitive data, so always run it over HTTPS. The simplest way is a reverse proxy like Caddy:

nextcloud.example.com {
    reverse_proxy localhost:8080
}

Caddy handles the TLS certificate automatically. After it’s running, set the trusted_domains in Nextcloud’s config/config.php to your domain so it accepts the new URL.

Performance tuning (optional but worth it)

Nextcloud runs fine out of the box, but a couple of tweaks make it noticeably snappier:

  • Add Redis for caching. It speeds up file listings and the web UI considerably. Point Nextcloud’s config.php at a Redis container.
  • Set up cron for background jobs. By default, Nextcloud runs background jobs when users visit, which can feel slow. Switching to a cron job smooths it out.
  • Increase PHP memory limits if you’re working with large files.

None of these are required to start, but they’re the difference between “fine” and “fast” once your library grows.

Troubleshooting common errors

  • “Cannot connect to database” — the database container isn’t ready yet. Wait a minute and retry, or check docker compose logs db.
  • 502 Bad Gateway — the reverse proxy can’t reach Nextcloud. Make sure the app container is up and the proxy points to localhost:8080.
  • Untrusted domain warning — you forgot to add your domain to trusted_domains. Edit config/config.php.

What to do after setup

  • Enable two-factor authentication. Your files deserve more than a password.
  • Install the desktop and mobile clients. Automatic sync is the whole point.
  • Explore apps. Calendar, Contacts, and Talk turn Nextcloud into a full Google replacement.

Common mistakes to avoid

  • Skipping HTTPS. Running Nextcloud over plain HTTP is asking for trouble. Always use a reverse proxy with TLS.
  • Losing your passwords. The database password in the compose file is your only key to the database. Store the file somewhere safe.
  • Forgetting backups. The nextcloud and db volumes hold everything. Back them up regularly.

FAQ

Is Nextcloud really free to self-host?

Yes. Nextcloud is open source (AGPL) and free to use. You only pay for the hardware it runs on.

Should I use PostgreSQL or MariaDB?

For a single-user or family setup, MariaDB is simpler and works great. PostgreSQL is slightly faster at scale, but the difference is negligible for a homelab.

Can I run Nextcloud on a Raspberry Pi?

Yes — we cover the hardware and performance trade-offs in our Raspberry Pi guide.

How do I update Nextcloud?

Run docker compose pull, then docker compose up -d, from your compose folder. The Docker image updates cleanly, and your data in the named volumes stays intact.

Nextcloud apps worth installing

Nextcloud’s real power is its app ecosystem. After setup, open the Apps menu and add:

  • Calendar and Contacts — replace Google Calendar and Contacts.
  • Talk — self-hosted video calls and chat.
  • Notes — a simple markdown notes app.
  • Photos — a basic gallery (though Immich is better for serious photo management).
  • Two-factor authentication — not glamorous, but essential.

Next steps

Self-hosting Nextcloud is one of the highest-impact projects you can do — it replaces a whole stack of paid cloud services with one app you own. When you’re comfortable, check out our guide to self-hosting a password manager with Vaultwarden to secure the rest of your setup.