Anime-Sanctuary

Nextcloud

Your files, your calendar and your contacts live on other people's servers, ones you never see. Let's install Nextcloud, an online space that runs on your own server, with two Docker containers.

Course
Tutorial 22 of 35
Time
40 min to read
Tested with
Commands: tested on Debian 13 (Nextcloud 34). The SSH tunnel and HTTPS aren't replayed here
What you will be able to do
  • Write a Compose file with Nextcloud and its MariaDB database.
  • Start it, log in with the admin account and declare your domain names.
  • Know what Nextcloud expects from an HTTPS proxy placed in front of it.
  • Back up the volumes, then update without losing anything.

Before you start: Docker and Docker Compose, Your first SSH connection, HTTPS with Let's Encrypt, Reverse proxy.

Contents
  1. What Nextcloud does
  2. Prepare the folder and the passwords
  3. Write the Compose file
  4. First start
  5. Log in with the admin account
  6. Declare the allowed domain names
  7. Switch to HTTPS
  8. Back up the volumes
  9. Restore a backup
  10. Update
  11. If it fails
  12. What's next
  13. Sources

How do you install Nextcloud with Docker Compose on Debian? You need a file of about thirty lines for the app and its database, and some care with the passwords. Allow forty minutes, or an hour if the terminal is new to you (read The terminal for beginners first), and a good part of that is watching Nextcloud install itself. You'll end up with your own file space, which you can back up and update at your own pace.

What Nextcloud does

Nextcloud is an online space for your files, and you alone hold the key. You drop files from a browser or an app, on a computer or a phone, and find them everywhere. It also handles a calendar and an address book. Nothing leaves your server.

We run it with Docker, as in Docker and Docker Compose. In short: a container is a box holding a ready-made program, and Compose is the file where you write which boxes to start. We need two: the app, and a database, a program that stores and finds very quickly what Nextcloud needs to know (who may do what, which file is where). We use MariaDB, a very common database program.

The route has three parts:

  • Steps 1 to 4: install Nextcloud and open it at home, without exposing it to the Internet. This is the essential part.
  • Steps 5 and 6: give it a domain name and encrypt it. Only do this if you want to open it to the Internet.
  • Steps 7 and 8: back up, then update.

Let's start with the folder where everything will live.

1Prepare the folder and the passwords

You need three passwords: the Nextcloud administrator's, the database's, and the one for the account that manages that database. Written in the Compose file, they would be easy to share by mistake. So we keep them apart, in a file named .env. In the Compose file, a word like ${NOM} is a blank to fill in. Compose reads it automatically, if it sits next to docker-compose.yml, and puts in the value written in .env.

The server generates the three passwords itself: 24 random lowercase letters and digits. You can copy the block as it is. The box below explains each tool, for the curious.

How the command makes the passwords

/dev/urandom is the server's source of randomness, tr keeps only lowercase letters and digits, and head -c 24 stops at 24 characters. The install -m 600 line creates the empty .env file, readable by your account alone, before the secrets are written into it.

On the server
mkdir -p ~/nextcloud
cd ~/nextcloud
DB_ROOT_PASSWORD=$(tr -dc 'a-z0-9' </dev/urandom | head -c 24)
DB_PASSWORD=$(tr -dc 'a-z0-9' </dev/urandom | head -c 24)
ADMIN_PASSWORD=$(tr -dc 'a-z0-9' </dev/urandom | head -c 24)
install -m 600 /dev/null .env
printf 'DB_ROOT_PASSWORD=%s\nDB_PASSWORD=%s\nADMIN_PASSWORD=%s\n' "$DB_ROOT_PASSWORD" "$DB_PASSWORD" "$ADMIN_PASSWORD" > .env
echo "Mot de passe de admincloud : $ADMIN_PASSWORD"

The last line prints your administrator account's password: 24 lowercase letters and digits. Copy it right away. Select the line with the mouse in the terminal, then press Ctrl+Shift+C (Cmd+C on a Mac). Store it in a password manager, a digital safe for your secrets (KeePassXC, which is free, is one example), because you will need it in a few minutes. Without a manager, a paper notebook does the job. You never need to know the other two.

The secrets are stored. Now describe the two containers.

2Write the Compose file

Here is the whole file. It builds on what you know from Docker and Docker Compose: a fixed-version image, a port reserved for the server, volumes. A volume is a folder that Docker keeps outside the container. If you recreate the box, the data stays. The command cat > docker-compose.yml <<'EOF' writes everything that follows into the file, up to the line EOF (the word that marks the end of the text). Copy it as it is. It reads your passwords from .env.

On the server
cat > docker-compose.yml <<'EOF'
services:
  db:
    image: mariadb:11.8
    restart: unless-stopped
    command: --transaction-isolation=READ-COMMITTED
    volumes:
      - db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: ${DB_PASSWORD}

  app:
    image: nextcloud:34-apache
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "127.0.0.1:8082:80"
    volumes:
      - nextcloud:/var/www/html
    environment:
      MYSQL_HOST: db
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: ${DB_PASSWORD}
      NEXTCLOUD_ADMIN_USER: admincloud
      NEXTCLOUD_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: cloud.exemple.fr

volumes:
  db:
  nextcloud:
EOF

Six choices deserve a word:

  • No ports on db: the database can only be reached by app, never from the Internet.
  • 127.0.0.1:8082:80 on app: the port is reserved for the server, as in the previous article. The HTTPS proxy will plug into it later.
  • Two volumes, two folders that persist: db keeps the database, and nextcloud keeps the program, the settings and all your files.
  • Fixed versions: 34-apache for Nextcloud (the variant that includes Apache, the software that answers browsers, covered in Your first website with Apache), and 11.8 for MariaDB, a version that Nextcloud's documentation accepts. Nothing changes unless you decide to.
  • NEXTCLOUD_ADMIN_USER and NEXTCLOUD_ADMIN_PASSWORD: they create the administrator account, admincloud, at first start. The setup wizard won't appear.
  • NEXTCLOUD_TRUSTED_DOMAINS: the names Nextcloud will agree to be called by. We come back to it in step 5.

The file is ready. Let's switch everything on.

3First start

The first start downloads the two images, which are fairly heavy, then installs Nextcloud into the volume. Allow one to two minutes after the download.

On the server
sudo docker compose up -d
sudo docker compose ps
Expected output
NAME              IMAGE                 COMMAND                  SERVICE   CREATED         STATUS                  PORTS
nextcloud-app-1   nextcloud:34-apache   "/entrypoint.sh apac..."   app       2 seconds ago   Up Less than a second   127.0.0.1:8082->80/tcp
nextcloud-db-1    mariadb:11.8          "docker-entrypoint.s..."   db        2 seconds ago   Up 1 second             3306/tcp

Both containers are running, but Nextcloud isn't ready. In the PORTS column, the database only shows 3306/tcp. Its port exists inside its box and isn't published anywhere. Follow the installation in the container's log. grep -E keeps only the lines that contain one of the two words we look for.

On the server
sudo docker compose logs app | grep -E "Retrying|successfully"
Expected output
app-1  | Retrying install...
app-1  | Retrying install...
app-1  | Nextcloud was successfully installed

The "Retrying install" lines are normal. Nextcloud starts before the database is ready, fails, then retries until the database answers. How many lines you see varies. Run the command again until you see "successfully installed", then check that the app answers.

On the server
curl -s http://127.0.0.1:8082/status.php
Expected output
{"installed":true,"maintenance":false,"needsDbUpgrade":false,"version":"34.0.5.1","versionstring":"34.0.5","edition":"","productname":"Nextcloud","extendedSupport":false}

Only "installed":true matters. Your version number may be newer than ours. Nextcloud runs, but it only answers on the server itself. So how do you open it from your computer?

4Log in with the admin account

To reach this port from home, open an SSH tunnel. Your computer's port 8082 gets linked, through the SSH connection, to the server's port 8082. It's the connection from Your first SSH connection, with the -L option added.

Two accounts come into play. In the command below, alice is your Linux account, the one for your SSH connection. Replace it with yours, and replace the address with your server's. The Nextcloud account, admincloud, created in step 2, is only used in the browser. Keep the tunnel window open as long as you use Nextcloud.

On your computer
ssh -L 8082:127.0.0.1:8082 alice@203.0.113.10

Then open http://localhost:8082 in your browser. Enter the username set in the Compose file (admincloud here) and the 24-character password you copied in step 1. You land in your own space. If the page doesn't open, check that the tunnel window is still open.

Check the account from the server (optional)

The occ command is Nextcloud's command-line tool. The -u www-data option runs it under the account that runs the app inside its box.

On the server
cd ~/nextcloud
sudo docker compose exec -u www-data app php occ user:list
Expected output
  - admincloud: admincloud

If the page opens and the password works, the essential part is done. Nextcloud runs at home, and only your computer reaches it, through the tunnel. The next two steps are only for opening it to the Internet under a domain name. If you don't need that, skip straight to step 7.

5Declare the allowed domain names

This step is only needed if you want to reach Nextcloud by a domain name. Nextcloud only answers to the names on its list of trusted domains (trusted_domains). It refuses the others, so nobody can call it under a fake name. Our file put cloud.exemple.fr there, and localhost is already on it. That's why the tunnel worked.

Read and change the list with occ

Here is the current list.

On the server
sudo docker compose exec -u www-data app php occ config:system:get trusted_domains
Expected output
localhost
cloud.exemple.fr

If you call Nextcloud by a name that isn't on the list, for example the server's address, it answers "Access through untrusted domain". To allow it, add that name to the list with occ. The number 2 is the new name's place in the list, whose first place is 0.

On the server
sudo docker compose exec -u www-data app php occ config:system:set trusted_domains 2 --value=203.0.113.10
sudo docker compose exec -u www-data app php occ config:system:get trusted_domains
Expected output
System config value trusted_domains => 2 set to string 203.0.113.10
localhost
cloud.exemple.fr
203.0.113.10

For cloud.exemple.fr to really lead to your server, you need a DNS record, as in Domain name and DNS. It's a line in the directory that links a name to your server's address. Before opening it to the Internet, one thing is left: encrypting it.

6Switch to HTTPS

Nextcloud only speaks HTTP, which means no encryption: everything travels in clear text. HTTPS is the same exchange, but encrypted. Without it, your passwords and your files travel in the open, so never open Nextcloud to the Internet without HTTPS.

To add it, you put a Reverse proxy in front of it. It's a doorman program that receives visitors over HTTPS and passes their request to 127.0.0.1:8082. It relies on the certificate from HTTPS with Let's Encrypt, a digital ID card that proves the site is really yours. Setting up this proxy is covered in its own article. If you stay at home with the tunnel, there's nothing to do here, so go to step 7. Otherwise, set up the proxy, then open the box below.

After setting up the proxy: tell Nextcloud it sits behind it

Once the proxy is in place, Nextcloud must know that visitors arrive over HTTPS, so it writes links starting with https://. In the docker-compose.yml file, under NEXTCLOUD_TRUSTED_DOMAINS and with the same indentation, add the following line, then recreate the container.

In docker-compose.yml
      OVERWRITEPROTOCOL: https
On the server
sudo docker compose up -d
sudo docker compose exec -u www-data app php occ config:system:get overwriteprotocol
Expected output
https

Careful: as long as this line is there, the SSH tunnel from step 4 stops working, because Nextcloud rewrites all its links as HTTPS. Open it by its HTTPS address. To get the tunnel back, remove the line and run up -d again.

Whether or not you opened Nextcloud to the Internet, make sure you can get your files back before you put real ones in.

7Back up the volumes

What matters lives in the two volumes: the database in one, the files and settings in the other. The backup copies both while Nextcloud is paused (its maintenance mode closes the site to visitors during the copy). Without this pause, a file could change between the two copies, and the database would no longer match the files.

Compose names volumes after the folder, so the files volume is called nextcloud_nextcloud here. Copy the block below as it is. The details of the tools are in the box just above it.

What the backup tools do
  • mariadb-dump exports the database to a text file, from the db container. The --single-transaction option avoids blocking reads.
  • tar archives the files, in a throwaway container made with alpine:3.20, a tiny Linux image.

Both files hold all your secrets: chmod 600 makes them readable by you alone. Docker created the archive in the server administrator's name, so chown first gives it back to your account. Otherwise chmod couldn't lock it down.

If a command fails, run occ maintenance:mode --off before looking for the cause, or the site stays closed.

On the server
cd ~/nextcloud
sudo docker compose exec -u www-data app php occ maintenance:mode --on
sudo docker compose exec -T db sh -c 'mariadb-dump --single-transaction -u root -p"$MYSQL_ROOT_PASSWORD" nextcloud' > nextcloud-base.sql
sudo docker run --rm -v nextcloud_nextcloud:/donnees:ro -v "$PWD":/sauvegarde alpine:3.20 tar czf /sauvegarde/nextcloud-fichiers.tar.gz -C /donnees .
sudo docker compose exec -u www-data app php occ maintenance:mode --off
sudo chown "$USER" nextcloud-fichiers.tar.gz && chmod 600 nextcloud-base.sql nextcloud-fichiers.tar.gz
Expected output
Maintenance mode enabled
Maintenance mode disabled

You now have two files in ~/nextcloud. The archive weighs several hundred MB, because the volume also holds the Nextcloud program. A backup that stays on the server won't protect you from a server failure, so copy it elsewhere, for example with Your first backup with rsync. Next, let's see how to put it back if the worst happens.

Restore a backup

A backup is only worth something if you can replay it. Restoring means putting the database back, then the files, with the app stopped. One detail to know: the backup was taken during maintenance, so after the restore Nextcloud still thinks it's in maintenance. The last command turns that mode off, and the site reopens.

The restore commands
On the server
cd ~/nextcloud
sudo docker compose stop app
sudo docker compose exec -T db sh -c 'mariadb -u root -p"$MYSQL_ROOT_PASSWORD" nextcloud' < nextcloud-base.sql
sudo docker run --rm -v nextcloud_nextcloud:/donnees -v "$PWD":/sauvegarde alpine:3.20 tar xzf /sauvegarde/nextcloud-fichiers.tar.gz -C /donnees
sudo docker compose start app
sudo docker compose exec -u www-data app php occ maintenance:mode --off
Expected output
Maintenance mode disabled

That leaves the day Nextcloud releases a new version.

8Update

An update replaces the container with a newer one that reuses the same volumes. Back up first, as in step 7, because a failed update doesn't undo itself. Then the method is the same as for any Compose service: download, then recreate.

On the server
cd ~/nextcloud
sudo docker compose pull
sudo docker compose up -d

At startup, Nextcloud compares the volume's version with the image's, and upgrades the database if they differ. Here is the version that runs.

On the server
sudo docker compose exec -u www-data app php occ status | head -3
Expected output
  - installed: true
  - version: 34.0.5.1
  - versionstring: 34.0.5

The tag is the part of the image name after the colon: 34-apache follows the 34 series. For the next series, change the number in the file, and don't skip any. Nextcloud only goes up one major version at a time, from 34 to 35, then from 35 to 36.

If it fails

Four situations come up again and again:

  • The page shows "Access through untrusted domain". The name typed in the browser isn't on the list. Add it as in step 5.
  • The "DB_PASSWORD" variable is not set. Defaulting to a blank string.. Compose didn't find the .env file. Go to ~/nextcloud and check with ls -a that the file is there. Don't start with empty passwords.
  • The log repeats "Connection refused" then "Retrying install...". That's normal during the first minute while the database starts. Wait for "successfully installed" to appear.
  • port is already allocated. Port 8082 is taken. Change the first 8082 in the file, as in the Docker article.

What's next

Your file space runs, with its database, its volumes and a backup. You can now use the same method for other services: one file, one folder, passwords kept apart. The next article, Jellyfin, applies it to a player for your own videos and music.

Sources (accessed November 4, 2026)