Skip to content

Tutorial

Automatic n8n backups: cron, encrypted copies and a tested restore

This guide turns the manual n8n backup into a daily one that runs on its own: a script dumps PostgreSQL, saves the .n8n folder and the .env with the encryption key, sends everything encrypted to an S3 bucket off the VPS and deletes old copies. At the end, you restore the copy into a separate project and check that the workflows came back and that the credentials can still be read.

On this page
  1. Before you start
  2. What goes into the backup
  3. Install rclone
  4. Set up the encrypted destination
  5. The backup script
  6. Schedule it with cron
  7. Test the restore
  8. Restore on a new VPS
  9. Next steps

Before you start

The starting point is the setup from How to install n8n with Docker on a VPS: n8n with PostgreSQL on Docker Compose, in /home/deploy/n8n. If your folder or service names are different, adjust the variables at the top of the script.

You also need a bucket in S3-compatible storage that is not on the same VPS: Backblaze B2, Cloudflare R2, Wasabi, Amazon S3 or another. Create the bucket and an access key that can only see that bucket. Note down the endpoint, the region, the bucket name and the key pair.

What goes into the backup

A backup that restores all of n8n has four parts:

  • The PostgreSQL database, with workflows, credentials (encrypted), users and execution history.
  • The .n8n folder, which lives in the n8n_data volume and holds the config file with the encryption key.
  • The .env, with N8N_ENCRYPTION_KEY and the database and runner passwords.
  • The docker-compose.yml and the Caddyfile, to bring the same stack up on a new VPS.

Install rclone

rclone copies files to almost any cloud storage and encrypts them on the way. The Ubuntu 24.04 package is several versions behind, so install the .deb from the project itself:

bash
cd /tmp
curl -fsSLO https://downloads.rclone.org/rclone-current-linux-$(dpkg --print-architecture).deb
sudo apt install ./rclone-current-linux-$(dpkg --print-architecture).deb
rclone version

The backup will run as root, from cron, so the rclone configuration also lives under root. That's why the commands below use sudo rclone.

Set up the encrypted destination

First, access to the bucket. read asks for the values without leaving them in your shell history:

bash
read -rp "S3 endpoint (https://...): " S3_ENDPOINT
read -rp "Region: " S3_REGION
read -rp "Access key ID: " S3_KEY
read -rsp "Secret access key: " S3_SECRET; echo

sudo rclone config create n8n-s3 s3 provider=Other \
  endpoint="$S3_ENDPOINT" region="$S3_REGION" \
  access_key_id="$S3_KEY" secret_access_key="$S3_SECRET" > /dev/null

sudo rclone lsd n8n-s3:

rclone config create prints the configuration it just created, secret key included; the > /dev/null keeps it off the screen. The last command lists the buckets the key can see. If your provider is on rclone's list (AWS, Cloudflare, Wasabi and others), replace provider=Other with its name.

Then, the encryption layer. It sits on top of the bucket, in an n8n folder, and encrypts both contents and file names before upload. Generate two long passwords and store both in a password manager before you continue:

bash
openssl rand -hex 32
openssl rand -hex 32
bash
read -rp "Bucket name: " S3_BUCKET
read -rsp "Encryption password: " CRYPT_PASS; echo
read -rsp "Second password (salt): " CRYPT_SALT; echo

sudo rclone config create n8n-offsite crypt \
  remote="n8n-s3:$S3_BUCKET/n8n" \
  password="$CRYPT_PASS" password2="$CRYPT_SALT" --obscure > /dev/null

echo "test" | sudo rclone rcat n8n-offsite:test.txt
sudo rclone cat n8n-offsite:test.txt
sudo rclone deletefile n8n-offsite:test.txt

rclone cat must print test. You can ignore the NOTICE about --checksum that rcat shows. In the provider's dashboard, the file shows up with a scrambled name inside n8n/.

The backup script

Create the script with sudo nano /usr/local/sbin/n8n-backup.sh and paste:

n8n-backup.sh
#!/usr/bin/env bash
# Daily n8n backup: database, .n8n folder and stack files,
# with an encrypted copy off the VPS.
set -euo pipefail

N8N_DIR=/home/deploy/n8n        # folder with docker-compose.yml
LOCAL_DIR=/var/backups/n8n      # local copies
REMOTE=n8n-offsite:             # encrypted rclone destination
KEEP_LOCAL_DAYS=7               # days of copies on the VPS
KEEP_REMOTE=30d                 # how long copies stay in the bucket

cd "$N8N_DIR"
set -a; . ./.env; set +a

STAMP=$(date +%F-%H%M)
DEST="$LOCAL_DIR/$STAMP"
install -d -m 700 "$LOCAL_DIR" "$DEST"

# 1. Database, in pg_restore format, and a check of the file
docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc > "$DEST/n8n-db.dump"
docker compose exec -T postgres pg_restore --list < "$DEST/n8n-db.dump" > /dev/null

# 2. The .n8n folder, from inside the volume
docker run --rm --volumes-from "$(docker compose ps -q n8n)" -v "$DEST":/backup \
  ubuntu:24.04 tar czf /backup/n8n-data.tar.gz -C /home/node .n8n

# 3. Stack files
cp .env "$DEST/env"
cp docker-compose.yml Caddyfile "$DEST/"

# 4. Off-site copy and check
rclone copy "$DEST" "$REMOTE$STAMP"
rclone cryptcheck "$DEST" "$REMOTE$STAMP"

# 5. Remove old copies
find "$LOCAL_DIR" -mindepth 1 -maxdepth 1 -type d -mtime +"$KEEP_LOCAL_DAYS" -exec rm -rf {} +
rclone delete "$REMOTE" --min-age "$KEEP_REMOTE"
rclone rmdirs "$REMOTE" --leave-root

echo "$(date -Is) backup $STAMP done"
bash
sudo chmod 700 /usr/local/sbin/n8n-backup.sh
sudo /usr/local/sbin/n8n-backup.sh
sudo rclone lsl n8n-offsite:

The first run must end with backup ... done, and rclone lsl must list five files inside a folder named with the date and time.

What's worth knowing about the script:

  • set -euo pipefail stops the script at the first error. A failed dump never reaches the bucket, and old copies aren't cleaned up.
  • The dump uses PostgreSQL's own format (-Fc) instead of the pg_dumpall from the install guide. It restores into a database that already exists, which is what a fresh Postgres container gives you. pg_restore --list reads the whole file and fails if it's corrupted.
  • pg_dump reads a consistent snapshot of the database while n8n keeps running. You don't need to stop the stack.
  • rclone cryptcheck checks every file in the bucket against the original by hash, without downloading anything.
  • The cleanup deletes local copies older than 7 days and bucket copies older than 30. Change KEEP_LOCAL_DAYS and KEEP_REMOTE if your database is large or you need to keep copies longer.

Schedule it with cron

Create /etc/cron.d/n8n-backup with sudo nano /etc/cron.d/n8n-backup:

n8n-backup
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
30 3 * * * root flock -n /run/n8n-backup.lock /usr/local/sbin/n8n-backup.sh >> /var/log/n8n-backup.log 2>&1

The backup runs every day at 3:30 in the VPS time zone. Check it with timedatectl: many VPSs run on UTC. If you change the time zone with sudo timedatectl set-timezone, restart cron with sudo systemctl restart cron, because it only reads the time zone when it starts. flock keeps two runs from overlapping, and each run's output goes to /var/log/n8n-backup.log.

Files in /etc/cron.d can't have a dot in their name and must end with a newline. Cron picks the file up on its own, without restarting anything. The next day, check:

bash
tail -n 5 /var/log/n8n-backup.log
sudo rclone lsd n8n-offsite:

Test the restore

A backup is only worth something if it restores. The test below downloads the latest copy from the bucket and restores it on the same VPS, in a separate Compose project. It publishes no ports and never starts the n8n server. That way no trigger or scheduled workflow runs twice, and the production instance stays untouched.

Download the latest copy:

bash
mkdir -p ~/n8n-restore-test && cd ~/n8n-restore-test

STAMP=$(sudo rclone lsf --dirs-only n8n-offsite: | sort | tail -n 1 | tr -d /)
echo "$STAMP"
[ -n "$STAMP" ] && sudo rclone copy "n8n-offsite:$STAMP" ./backup
sudo chown -R "$USER": backup

cp backup/env .env
cp backup/docker-compose.yml backup/Caddyfile .
chmod 600 .env
set -a && . ./.env && set +a

The echo must print the date and time of the copy; if it prints nothing, the bucket has no backup and the next command downloads nothing.

Because the folder is called n8n-restore-test, Compose creates containers and volumes with that prefix, separate from production. Restore the database into a fresh Postgres:

bash
sudo docker compose up -d --wait postgres
sudo docker compose exec -T postgres pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner --exit-on-error < backup/n8n-db.dump

Put the .n8n folder back into the n8n volume:

bash
sudo docker compose run --rm --no-deps -v "$PWD/backup":/backup --entrypoint tar n8n xzf /backup/n8n-data.tar.gz -C /home/node

Now check the workflows and credentials with the n8n command line, which runs and exits without starting the server:

bash
sudo docker compose run --rm --no-deps n8n export:workflow --all --pretty | grep '"name"' | head
sudo docker compose run --rm --no-deps n8n export:credentials --all --decrypted --pretty | grep -c '"data"'

The first command lists the names of the workflows and their nodes. The second counts the credentials n8n could open with the key from the backup; the number must match the total number of credentials in your instance. If it prints 0 along with Credentials could not be decrypted or Mismatching encryption keys, the key in the backup doesn't match the database, and this backup wouldn't restore your credentials. Neither command writes anything to disk, but the second one reads the decrypted credentials: don't swap grep -c for something that prints them.

Finally, remove the test environment. Here, and only here, -v is what you want, because it deletes the test volumes:

bash
cd ~/n8n-restore-test
sudo docker compose down -v
cd ~ && rm -rf ~/n8n-restore-test

Repeat the test from time to time, for example after each n8n update or once a month.

Restore on a new VPS

If you lose the VPS, the path is the same as the test, with the production stack:

  1. Install Docker and rclone on the new VPS, as in the install guide and in this one.
  2. Recreate both rclone destinations with the same bucket keys and the same two passwords from your password manager.
  3. Download the latest copy into /home/deploy/n8n/backup and put env (renamed to .env), docker-compose.yml and Caddyfile in /home/deploy/n8n.
  4. Start only Postgres, then restore the database and the .n8n folder with the same commands as the test.
  5. Point DNS to the new IP and bring the whole stack up with sudo docker compose up -d.
  6. Sign in to the editor with the same account as before and, once you've checked, delete the backup folder, which holds a copy of the .env.

Next steps

  • If your bucket provider allows it, use a key that can list, read and write but not delete, and turn on bucket versioning or object lock. Retention then moves to a bucket lifecycle rule, and the two rclone cleanup lines come out of the script. That way, someone who breaks into the VPS can't delete or overwrite the older copies. The key can't be write-only: rclone copy, cryptcheck and the restore all need to list and read the bucket.
  • Keep the .env and both rclone passwords in a password manager, off the VPS and outside the bucket.
  • For the whole server, not just n8n, a versioned and deduplicated backup, such as restic's, is the next step up.