You'll need the host running the app with MySQL or MariaDB, mysqldump and gzip (in the MySQL/MariaDB client package), and somewhere off-box. That can be another server you can rsync to over SSH (192.0.2.10 in the examples) or an object storage bucket with rclone configured.

Keep the password off the command line

A password on the command line shows up in ps and shell history. Put it in /root/.backup.my.cnf instead:

[client]
user=backup
password=long-random-string

chmod 600 /root/.backup.my.cnf

Give that MySQL user only what a dump needs, which is SELECT, SHOW VIEW, TRIGGER, LOCK TABLES and PROCESS. MySQL 8 wants PROCESS for tablespace information, or you can use --no-tablespaces.

The script

Save this as /usr/local/sbin/backup-myapp.sh:

#!/usr/bin/env bash
set -euo pipefail

APP="myapp"
DB_NAME="myapp"
APP_DIR="/var/www/myapp"
BACKUP_DIR="/var/backups/${APP}"
RETENTION_DAYS=14
REMOTE="backup@192.0.2.10:/srv/backups/${APP}/"
STAMP="$(date +%F_%H%M)"

umask 077
mkdir -p "${BACKUP_DIR}"

DB_FILE="${BACKUP_DIR}/${APP}_db_${STAMP}.sql.gz"
FILES_FILE="${BACKUP_DIR}/${APP}_files_${STAMP}.tar.gz"

# Remove partial files if anything fails
cleanup() { rm -f "${DB_FILE}.tmp" "${FILES_FILE}.tmp"; }
trap cleanup EXIT

echo "$(date -Is) starting backup of ${APP}"

# 1. Database: consistent snapshot without locking InnoDB tables
mysqldump --defaults-extra-file=/root/.backup.my.cnf \
    --single-transaction --quick --routines --triggers --no-tablespaces \
    "${DB_NAME}" | gzip > "${DB_FILE}.tmp"
gzip -t "${DB_FILE}.tmp"
mv "${DB_FILE}.tmp" "${DB_FILE}"

# 2. Uploads and config
tar -czf "${FILES_FILE}.tmp" -C "${APP_DIR}" uploads config
mv "${FILES_FILE}.tmp" "${FILES_FILE}"

# 3. Local retention
find "${BACKUP_DIR}" -type f -name "${APP}_*" -mtime +"${RETENTION_DAYS}" -delete

# 4. Off-box copy
rsync -a "${BACKUP_DIR}/" "${REMOTE}"

echo "$(date -Is) backup of ${APP} complete"

chmod 700 /usr/local/sbin/backup-myapp.sh
/usr/local/sbin/backup-myapp.sh
ls -lh /var/backups/myapp/

A few parts of that script are there because they've burned us before. set -euo pipefail stops the script on any error, including a failed mysqldump in the middle of a pipe. Without pipefail, a failed dump piped into a successful gzip counts as success, and you get a tiny, useless file every night.

--single-transaction takes a consistent snapshot of InnoDB tables without locking them, so people can keep using the app during the dump. It doesn't protect MyISAM tables, so if your app still uses those, check before relying on it. --quick streams rows instead of buffering whole tables in memory.

Writing to .tmp and renaming means a failed run never leaves behind a file that looks like a good backup, and gzip -t checks the archive is intact. The find -mtime +14 -delete line removes local copies older than 14 days, matched by name so it can't wander into other files.

rsync -a without --delete means the remote keeps files even after local retention removes them, so give the remote its own retention job. That longer remote history matters more than it sounds. If backups have been failing for longer than your local retention window, local cleanup can leave you with nothing usable, and the remote is all you've got.

Getting a copy off the box

For rsync, set up an SSH key for root to the backup host and restrict it on that end. For object storage, swap the last step for rclone:

rclone copy "${BACKUP_DIR}" "b2:example-backups/${APP}" --max-age 48h

On-box backups cover you for a bad update or an accidental delete. They do nothing for a dead disk, a deleted VM, a compromised host or ransomware, because those take the backups along with the data. I like a pull-based setup even better, where the backup server connects in and fetches the files, so a compromised app server has no credentials that can delete the backup history. Object storage with versioning or object lock gets you something similar.

Scheduling

Create /etc/cron.d/backup-myapp:

30 2 * * * root /usr/local/sbin/backup-myapp.sh >> /var/log/backup-myapp.log 2>&1

Files in /etc/cron.d need the user field (root here), unlike a personal crontab. Pick a quiet time and stagger it from other heavy jobs.

Cron won't tell anyone when a job fails. Have the script ping a dead man's switch service (healthchecks-style) on success, so you get alerted when the ping doesn't arrive.

LATEST=$(ls -1t /var/backups/myapp/myapp_db_*.sql.gz | head -n1)

mysql -u root -p -e "CREATE DATABASE restore_test;"
gunzip -c "$LATEST" | mysql -u root -p restore_test
mysql -u root -p -e "SELECT table_name, table_rows FROM information_schema.tables WHERE table_schema='restore_test';"
mysql -u root -p -e "DROP DATABASE restore_test;"

mkdir -p /tmp/restore-test
tar -xzf "$(ls -1t /var/backups/myapp/myapp_files_*.tar.gz | head -n1)" -C /tmp/restore-test
ls -R /tmp/restore-test | head
rm -rf /tmp/restore-test

You'll need Docker Engine with the Compose plugin (docker compose, not the old docker-compose), and root or sudo.

One directory per app under /opt

/opt/wiki/
  compose.yaml
  .env
  data/          # bind-mounted application data
  db/            # bind-mounted database data

Everything about the app lives in one place, so backing it up, moving it or rebuilding the host means dealing with one directory. Compose also uses the directory name as the project name, so containers and networks get predictable names.

Secrets go in .env, locked down

DB_PASSWORD=long-random-string
APP_SECRET=another-long-random-string

chmod 600 /opt/wiki/.env
chown root:root /opt/wiki/.env

Compose reads .env from the project directory automatically for variable substitution, so compose.yaml can reference ${DB_PASSWORD} and still be safe to share or commit. Never commit the .env itself.

The compose file

services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wiki
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./db:/var/lib/postgresql/data

  app:
    image: ghcr.io/example/wiki:2.5
    restart: unless-stopped
    depends_on:
      - db
    environment:
      DB_HOST: db
      DB_PASSWORD: ${DB_PASSWORD}
      APP_SECRET: ${APP_SECRET}
    ports:
      - "127.0.0.1:8080:3000"
    volumes:
      - ./data:/app/data

A few things in there are on purpose. unless-stopped brings containers back after a crash or reboot but respects a deliberate docker compose stop. With no restart policy, nothing comes back after a reboot, and you find out when someone calls.

The image is pinned to :2.5 rather than :latest, so an update is a decision and not a surprise. I bump the tag after reading the release notes.

The app is published on 127.0.0.1 only because a reverse proxy on the same host fronts it. Docker's port publishing bypasses typical host firewall rules, so don't count on those. The app reaches the database as db on the project's default network, which means the database port never gets published at all.

Bind mounts or named volumes?

For self-hosting I prefer bind mounts (./data:/app/data) inside the project directory. The data sits in a directory you chose, you can see it, back it up with ordinary tools, and it moves with the project. Named volumes are managed by Docker under /var/lib/docker/volumes/ and avoid some file-ownership headaches, but they're easier to lose track of, and docker compose down -v deletes them. If your data is in named volumes, that's your data gone. Bind mounts aren't touched. We only use named volumes where an image's documentation strongly recommends them.

The cost of bind mounts is permissions. Containers that run as a non-root user need the host directory owned by that UID. Check the image docs, then chown -R the host directory to match before first start.

Day to day

cd /opt/wiki
docker compose up -d                 # create or update and start everything
docker compose ps                    # status
docker compose logs -f --tail=100 app
docker compose restart app
docker compose down                  # stop and remove containers (data stays)

Updating without surprises

cd /opt/wiki
# 1. back up first (Step 6)
# 2. change the image tag in compose.yaml if moving versions
docker compose pull
docker compose up -d
docker compose logs -f --tail=100
docker image prune -f

pull fetches new images and up -d recreates only the containers whose image or configuration changed. Watch the logs until migrations finish before you call it done.

Backups

For a consistent copy, stop the stack, archive the directory and start it again:

cd /opt
docker compose -f /opt/wiki/compose.yaml stop
tar -czf /var/backups/wiki-$(date +%F).tar.gz wiki
docker compose -f /opt/wiki/compose.yaml start

If you can't take the downtime, dump the database with its own tool instead (for example docker compose exec -T db pg_dump -U wiki wiki) and archive the data directory alongside it. Either way, copy the result off the host.

Cap the logs before they fill the disk

The default json-file log driver has no size limit. Set one in /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Restart Docker afterwards. It only applies to newly created containers, so run docker compose up -d --force-recreate in each project to pick it up.

    volumes:
      - ./data:/app/data
      - ./config/custom.ini:/app/config/custom.ini:ro

If you only have time for one of those, do the restore test. It's the one that tells you whether the rest of this was worth it.

You'll need Docker Engine with the Compose plugin, and root or sudo. Make sure no MySQL or MariaDB server package is installed on the host, because it will fight over port 3306 and /run/mysqld. Client packages are fine.

Project directory and root password

mkdir -p /opt/mysql/data
cd /opt/mysql

Put the root password in /opt/mysql/.env and lock it down:

MYSQL_ROOT_PASSWORD=change-me-to-a-long-random-string

chmod 600 /opt/mysql/.env

A socket directory that survives reboots

/var/run is a symlink to /run, which is a tmpfs, so anything you create there is gone after a reboot. A tmpfiles.d entry recreates it at boot with the right owner, before Docker starts the container. Without it, Docker creates the missing bind-mount source itself as a root-owned directory, and depending on the image and timing, mysqld may not be able to create its socket there. I'd rather not leave that to luck.

First check the UID of the mysql user inside the image:

docker run --rm mysql:8.4 id mysql

In the official image that's UID and GID 999. Create /etc/tmpfiles.d/mysqld-docker.conf:

d /run/mysqld 0755 999 999 -

The 0755 matters. The socket file itself is world-writable, but the host user (www-data, for example) has to be able to enter the directory, or the app gets "Permission denied" on the socket. Apply it now without rebooting:

systemd-tmpfiles --create /etc/tmpfiles.d/mysqld-docker.conf
ls -ld /run/mysqld

The compose file

/opt/mysql/compose.yaml:

services:
  mysql:
    image: mysql:8.4
    container_name: mysql
    restart: unless-stopped
    env_file: .env
    ports:
      - "127.0.0.1:3306:3306"
    volumes:
      - ./data:/var/lib/mysql
      - /var/run/mysqld:/var/run/mysqld

127.0.0.1:3306:3306 publishes the port on loopback only. Leave the IP prefix off and Docker publishes on all interfaces, and Docker's own firewall rules are applied ahead of most host firewall setups, so a ufw "deny 3306" won't save you.

Bind-mounting /var/run/mysqld puts the container's socket directory on the host. When mysqld creates mysqld.sock inside the container, it shows up on the host at the same path.

Start it and check the socket

docker compose up -d
docker compose logs -f mysql      # wait for "ready for connections", then Ctrl+C
ls -l /var/run/mysqld/

You should see mysqld.sock. Confirm the server agrees on the path:

docker exec -it mysql mysql -uroot -p -e "SHOW VARIABLES LIKE 'socket';"

If your image version reports the socket somewhere else, change the bind mount to match that directory, or set the socket path explicitly in a config file mounted into /etc/mysql/conf.d/.

The app's database and user

docker exec -it mysql mysql -uroot -p

CREATE DATABASE appdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'appuser'@'localhost' IDENTIFIED BY 'another-long-random-string';
GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'localhost';

apt install -y default-mysql-client
mysql -u appuser -p appdb -e "SELECT CURRENT_USER(), @@hostname;"
mysql -h 127.0.0.1 -u root -p -e "SELECT 1;"
ss -ltnp | grep 3306

Two details get missed almost every time. The app needs to see the real client IP instead of the proxy's, and PHP needs to know the original request was HTTPS. Miss those and you get logs full of one IP, broken rate limiting and redirect loops.

Install nginx and PHP-FPM

apt update
apt install -y nginx php-fpm php-mysql php-xml php-mbstring php-curl php-zip
systemctl enable --now nginx php8.2-fpm
ls /run/php/

On Debian 12 the default PHP is 8.2 and the FPM socket is /run/php/php8.2-fpm.sock. Use whatever the ls actually shows you.

The proxy side

The proxy has to pass along the original host, client IP and scheme. In plain nginx on the proxy:

location / {
    proxy_pass http://10.10.20.21;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Most GUI proxies, Nginx Proxy Manager included, set these headers for you.

The app's nginx site

Create /etc/nginx/sites-available/app.conf:

# Translate the proxy's scheme header into an on/off value for PHP
map $http_x_forwarded_proto $https_flag {
    default off;
    https   on;
}

server {
    listen 80;
    server_name app.example.com;
    root /var/www/app/public;
    index index.php index.html;

    # Trust X-Forwarded-For only from our reverse proxy
    set_real_ip_from 10.10.20.5;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    client_max_body_size 64m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param HTTPS $https_flag;
    }

    location ~ /\.(?!well-known) {
        deny all;
    }
}

The map block sits outside server because it has to be in the http context. Debian includes site files inside http, so that's fine.

set_real_ip_from plus real_ip_header make nginx replace $remote_addr with the client IP from the header, but only when the request comes from the trusted proxy. Anyone else sending a forged header gets ignored.

fastcgi_param HTTPS sets $_SERVER['HTTPS'], which is what most PHP apps and frameworks check when building URLs and deciding whether to redirect. Debian's fastcgi.conf (included by the snippet) also sends HTTPS $https if_not_empty, but $https is empty on a plain HTTP listener, so only our value is sent. If the app has a "force HTTPS" setting and this flag isn't passed, it sees every request as plain HTTP and redirects forever. Some frameworks also need their own trusted proxy setting (Laravel's TrustProxies, for example).

A lot of guides online tell you to add try_files $uri =404; inside the PHP location. On Debian and Ubuntu, snippets/fastcgi-php.conf already has a try_files line, so adding yours makes nginx -t fail with "try_files" directive is duplicate. Leave it out. The snippet already returns 404 for PHP files that don't exist.

Enable the site and remove the default one:

ln -s /etc/nginx/sites-available/app.conf /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default
nginx -t && systemctl restart nginx

Lock down the backend

Only the proxy should be able to reach port 80 on the app container. If clients can hit it directly, they can bypass the proxy and send whatever X-Forwarded-Proto they like. Use the Proxmox firewall, nftables or your network firewall to allow TCP 80 from 10.10.20.5 only.

One more thing that bites the first time someone tries to upload a big file. client_max_body_size has to be raised on both the proxy and the backend, and PHP's upload_max_filesize and post_max_size in /etc/php/8.2/fpm/php.ini need to match. If they don't, uploads fail with a 413. Restart php8.2-fpm after changing them.

cat > /var/www/app/public/ipcheck.php <<'EOF'
<?php
header('Content-Type: text/plain');
echo 'REMOTE_ADDR: ' . $_SERVER['REMOTE_ADDR'] . "\n";
echo 'HTTPS: ' . ($_SERVER['HTTPS'] ?? '(unset)') . "\n";
EOF