How to migrate n8n to a new server?

Migrating n8n to a new server involves backing up your data from the existing server, installing n8n on the new server, and then restoring your data. This process ensures your workflows, credentials, and other settings are preserved during the transition, minimizing downtime and preventing data loss.

 

Step 1: Prepare for Migration

 

Before starting the migration process, ensure you have the following:

• Access to both the source and destination servers
• SSH access to both servers
• Root or sudo privileges on both servers
• Sufficient disk space on the new server
• Knowledge of your current n8n installation method (Docker, npm, etc.)

It's also recommended to:

• Check the current version of n8n you're running
• Document your current configuration settings
• Plan for downtime during the migration
• Notify users of the planned maintenance window

 

Step 2: Identify Your Current Installation Type

 

n8n can be installed in different ways, and the migration process varies slightly depending on your installation method. Determine how n8n is currently installed:

# For Docker installations, check if Docker is running
docker ps | grep n8n

# For npm installations, check the global packages
npm list -g n8n

# For PM2 managed installations
pm2 list | grep n8n

 

Step 3: Back Up Your Data

 

The most important part of migration is backing up your data. The location of your data depends on your installation method.

For Docker installations:

# Find your n8n data volume
docker volume ls | grep n8n

# Create a backup directory
mkdir -p ~/n8n-backup

# Export the n8n data volume (replace n8n\_data with your actual volume name)
docker run --rm -v n8n\_data:/source -v ~/n8n-backup:/backup alpine tar -czf /backup/n8n-data-backup.tar.gz -C /source .

For npm/PM2 installations (default data location is ~/.n8n):

# Create a backup of your n8n data directory
tar -czf ~/n8n-backup.tar.gz ~/.n8n

If you're using an external database:

# For PostgreSQL
pg_dump -U username -h hostname database_name > ~/n8n-db-backup.sql

# For MySQL/MariaDB
mysqldump -u username -p database\_name > ~/n8n-db-backup.sql

 

Step 4: Back Up Your Environment Variables and Configuration

 

n8n uses environment variables for configuration. Make sure to document all the environment variables you've set:

# For Docker, check your docker-compose.yml file or docker run command
# For npm/PM2 installations, check your startup script or .env file

# Example of backing up environment variables from a running Docker container
docker inspect n8n | grep -A 20 "Env"

# Or copy your .env file if you're using one
cp /path/to/.env ~/n8n-env-backup

 

Step 5: Transfer Backup Files to New Server

 

Transfer your backup files to the new server using SCP, SFTP, or any file transfer method:

# Using SCP (from your local machine)
scp ~/n8n-backup.tar.gz user@new-server-ip:~
scp ~/n8n-env-backup user@new-server-ip:~
scp ~/n8n-db-backup.sql user@new-server-ip:~ # If applicable

 

Step 6: Install n8n on the New Server

 

Install n8n on the new server using the same method as your original installation:

For Docker installation:

# Install Docker if not already installed
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose if needed
sudo curl -L "https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Create a docker-compose.yml file with your configuration
cat > docker-compose.yml << EOL
version: '3'
services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
    - "5678:5678"
    environment:
    - N8N_BASIC_AUTH\_ACTIVE=true
    - N8N_BASIC_AUTH\_USER=user
    - N8N_BASIC_AUTH\_PASSWORD=password
      # Add all your environment variables here
    volumes:
    - n8n\_data:/home/node/.n8n
volumes:
  n8n\_data:
EOL

# Start n8n
docker-compose up -d

For npm installation:

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup\_16.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install n8n
sudo npm install -g n8n

# Install PM2 if you were using it
sudo npm install -g pm2

 

Step 7: Restore Your Data

 

Stop the n8n service before restoring your data:

# For Docker
docker-compose down

# For npm/PM2
pm2 stop n8n

Now restore your data:

For Docker installations:

# Extract the backup to the new volume
mkdir -p ~/n8n-data-temp
tar -xzf ~/n8n-backup.tar.gz -C ~/n8n-data-temp

# Copy the data to the Docker volume
docker run --rm -v n8n\_data:/destination -v ~/n8n-data-temp:/source alpine sh -c "rm -rf /destination/_ && cp -R /source/_ /destination/"

# Clean up
rm -rf ~/n8n-data-temp

For npm/PM2 installations:

# Create the .n8n directory if it doesn't exist
mkdir -p ~/.n8n

# Extract the backup
tar -xzf ~/n8n-backup.tar.gz -C ~

If you're using an external database:

# For PostgreSQL
psql -U username -h hostname database\_name < ~/n8n-db-backup.sql

# For MySQL/MariaDB
mysql -u username -p database\_name < ~/n8n-db-backup.sql

 

Step 8: Configure Environment Variables

 

Restore your environment variables on the new server:

For Docker using docker-compose.yml:

# Edit your docker-compose.yml file to include all your environment variables
nano docker-compose.yml

For npm/PM2 installations, create an .env file:

# Create or edit your .env file
nano ~/.n8n/.env

# Or update your PM2 startup script
pm2 start n8n --update-env -- start

 

Step 9: Start n8n on the New Server

 

Start n8n after restoring your data and configuration:

# For Docker
docker-compose up -d

# For npm/PM2
pm2 start n8n

 

Step 10: Verify the Migration

 

After starting n8n, verify that everything is working correctly:

• Check that you can access the n8n interface
• Verify that all your workflows are present
• Confirm that your credentials are available
• Test a few workflows to ensure they run properly
• Check the logs for any errors

# Check Docker logs
docker logs -f n8n

# Check npm/PM2 logs
pm2 logs n8n

 

Step 11: Update DNS or IP References

 

If your n8n instance was accessible via a domain name, update your DNS records to point to the new server:

# Example DNS record update (using your DNS provider's interface)
# A record: n8n.yourdomain.com -> new-server-ip

If you have webhook URLs or other references to your n8n instance, make sure to update them.

 

Step 12: Set Up SSL (If Applicable)

 

If you were using SSL on your original server, set it up on the new server as well:

# Using Certbot with Nginx for Let's Encrypt SSL
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d n8n.yourdomain.com

 

Step 13: Configure Automatic Backups

 

Set up a backup routine for your new n8n instance:

# Create a backup script
cat > ~/backup-n8n.sh << 'EOL'
#!/bin/bash
BACKUP\_DIR="/path/to/backups"
TIMESTAMP=$(date +"%Y%m%d\_%H%M%S")
BACKUP_FILE="$BACKUP_DIR/n8n_backup_$TIMESTAMP.tar.gz"

# For Docker
docker run --rm -v n8n_data:/source -v $BACKUP_DIR:/backup alpine tar -czf /backup/n8n_backup_$TIMESTAMP.tar.gz -C /source .

# For npm/PM2
# tar -czf $BACKUP\_FILE ~/.n8n

# Cleanup old backups (keep last 7 days)
find $BACKUP_DIR -name "n8n_backup\_\*.tar.gz" -type f -mtime +7 -delete
EOL

# Make the script executable
chmod +x ~/backup-n8n.sh

# Set up a cron job to run daily
(crontab -l 2>/dev/null; echo "0 2 _ _ \* /home/username/backup-n8n.sh") | crontab -

 

Step 14: Monitor the New Installation

 

Set up monitoring for your new n8n instance:

# Install monitoring tools like Prometheus, Grafana, or simple uptime checks
# Example for a simple uptime check with cron
cat > ~/check-n8n.sh << 'EOL'
#!/bin/bash
URL="http://localhost:5678"
if ! curl -s --head $URL | grep "200 OK" > /dev/null; then
  echo "n8n seems to be down!" | mail -s "n8n Alert" [email protected]
fi
EOL

chmod +x ~/check-n8n.sh
(crontab -l 2>/dev/null; echo "_/5 _ _ _ \* /home/username/check-n8n.sh") | crontab -

 

Step 15: Document Your New Setup

 

Create documentation for your new n8n installation:

• Server details (IP, hostname, specs)
• Installation method and version
• Configuration settings and environment variables
• Backup procedures
• Monitoring setup
• Troubleshooting notes

 

Step 16: Clean Up Old Server (Optional)

 

Once you're confident that the migration is successful and everything is working properly on the new server, you can clean up the old server:

# For Docker
docker-compose down
docker volume rm n8n\_data

# For npm/PM2
pm2 delete n8n
npm uninstall -g n8n

# Backup the data one last time before removing
tar -czf ~/final-n8n-backup.tar.gz ~/.n8n
rm -rf ~/.n8n

 

Troubleshooting Common Migration Issues

 

Issue 1: Workflows Not Appearing After Migration

This could be due to incorrect data restoration or database configuration.

# Check the n8n logs for errors
docker logs n8n
# or
pm2 logs n8n

# Verify the database connection settings in your environment variables
# Make sure the database exists and the user has proper permissions

Issue 2: Credentials Not Working

Encrypted credentials might not work if your encryption key changed.

# Ensure you've set the same N8N_ENCRYPTION_KEY on the new server
# If you didn't have this variable before, you might need to recreate your credentials

Issue 3: Cannot Connect to Database

# Check if the database is running
systemctl status postgresql
# or
docker ps | grep postgres

# Verify network connectivity
telnet database-host database-port

# Check database user permissions

Issue 4: File Permission Problems

# For npm installations, ensure proper ownership of the .n8n directory
sudo chown -R $(whoami):$(whoami) ~/.n8n

# For Docker, check the permissions inside the container
docker exec -it n8n sh
ls -la /home/node/.n8n

Issue 5: Port Conflicts

# Check if another service is using port 5678
sudo netstat -tulpn | grep 5678

# If needed, change the port in your configuration

By following these detailed steps, you should be able to successfully migrate your n8n instance to a new server with minimal downtime and without losing any of your workflows, credentials, or settings.