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.
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
.n8nfolder, which lives in then8n_datavolume and holds theconfigfile with the encryption key. -
The
.env, withN8N_ENCRYPTION_KEYand the database and runner passwords. -
The
docker-compose.ymland theCaddyfile, to bring the same stack up on a new VPS.
Without the key, the credentials are lost. The database restores and the workflows show up, but n8n can't read any saved credential. That's why the
.envgoes along, and why the copy that leaves the VPS has to be encrypted.
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:
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:
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:
openssl rand -hex 32
openssl rand -hex 32
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/.
Without both passwords, the backup won't open. The rclone documentation is blunt about it: lose the password and you lose the data. The file
/root/.config/rclone/rclone.confkeeps the passwords only obscured, not protected; don't copy it anywhere public.
The backup script
Create the script with sudo nano /usr/local/sbin/n8n-backup.sh and paste:
#!/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"
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 pipefailstops 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 thepg_dumpallfrom the install guide. It restores into a database that already exists, which is what a fresh Postgres container gives you.pg_restore --listreads the whole file and fails if it's corrupted. -
pg_dumpreads a consistent snapshot of the database while n8n keeps running. You don't need to stop the stack. -
rclone cryptcheckchecks 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_DAYSandKEEP_REMOTEif 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:
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:
tail -n 5 /var/log/n8n-backup.log
sudo rclone lsd n8n-offsite:
A backup that fails silently isn't a backup. Cron doesn't tell anyone when the script fails. A cron monitoring service such as Healthchecks.io emails you when the day's run doesn't check in: add
curl -fsS -m 10 --retry 3 https://hc-ping.com/YOUR-UUIDas the last line of the script.
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:
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:
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:
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:
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:
cd ~/n8n-restore-test
sudo docker compose down -v
cd ~ && rm -rf ~/n8n-restore-test
Check the folder before
down -v. The command deletes the volumes of the project in the folder you're in. In~/n8n, it would delete the production database and key.
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:
- Install Docker and rclone on the new VPS, as in the install guide and in this one.
- Recreate both rclone destinations with the same bucket keys and the same two passwords from your password manager.
- Download the latest copy into
/home/deploy/n8n/backupand putenv(renamed to.env),docker-compose.ymlandCaddyfilein/home/deploy/n8n. - Start only Postgres, then restore the database and the
.n8nfolder with the same commands as the test. - Point DNS to the new IP and bring the whole stack up with
sudo docker compose up -d. - Sign in to the editor with the same account as before and, once you've checked, delete the
backupfolder, 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
rclonecleanup 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,cryptcheckand the restore all need to list and read the bucket. - Keep the
.envand 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.
Top comments (0)