Skip to content

INSTALL.md

Latest commit

 

History

History
640 lines (459 loc) · 13.9 KB

INSTALL.md

File metadata and controls

640 lines (459 loc) · 13.9 KB

Detailed Installation Guide

This guide provides step-by-step instructions for deploying n8n to Google Cloud Platform.

Table of Contents

Prerequisites

Before you begin, ensure you have the following:

1. Google Cloud SDK (gcloud)

The gcloud command-line tool must be installed and configured on your local machine.

Installation:

Verification:

gcloud --version

2. GCP Authentication

You must be authenticated with your Google account:

gcloud auth login

3. GCP Project

You need a GCP project with:

  • ✅ Billing enabled
  • ✅ Compute Engine API enabled
  • ✅ Proper IAM permissions

Required IAM roles:

  • Compute Admin
  • Service Account User

Enable Compute Engine API:

gcloud services enable compute.googleapis.com --project=YOUR_PROJECT_ID

4. Domain Name

You need a registered domain name that you can manage. You will create a DNS A record for this domain during deployment.

Recommended domain registrars:

  • Cloudflare
  • Google Domains
  • Namecheap
  • GoDaddy

Installation Methods

Method 1: One-Liner (Recommended)

Install and deploy with a single command:

curl -fsSL https://raw.githubusercontent.com/llmx-de/n8n-cloud-deploy/main/install.sh | bash

What it does:

  1. Downloads all necessary files to ~/n8n-cloud-deploy
  2. Sets permissions
  3. Optionally starts deployment immediately

Method 2: Clone Repository

For more control or offline use:

# Clone the repository
git clone https://github.com/llmx-de/n8n-cloud-deploy.git
cd n8n-cloud-deploy

# Make scripts executable
chmod +x provision-cloud.sh setup-instance.sh cleanup.sh

# Run deployment
bash provision-cloud.sh

Deployment Process

Step 1: Run the Deployment Script

bash provision-cloud.sh

Step 2: Interactive Setup

The script will guide you through the following prompts:

2.1 Project Selection

If you have multiple GCP projects, you'll see a numbered menu:

Available GCP Projects:
1) my-project-1
2) my-project-2
3) my-project-3
#? 2

If you have only one project, it will be auto-selected.

2.2 Region Selection

Choose the region closest to your users:

Select a GCP Region (recommended: regions close to your users):
Tip: Europe regions start with 'europe-', US with 'us-', Asia with 'asia-'

 1) asia-east1          11) europe-west1       21) us-central1
 2) asia-east2          12) europe-west2       22) us-east1
 ...
#? 11

Popular choices:

  • US users: us-central1, us-east1
  • EU users: europe-west1, europe-west3
  • Asia users: asia-southeast1, asia-northeast1

2.3 Zone Selection

Select a zone within your chosen region:

Select a Zone in europe-west1:
1) europe-west1-b
2) europe-west1-c
3) europe-west1-d
#? 1

2.4 Machine Type Selection

Choose the VM size based on your needs:

Select a machine type for your n8n instance:

Machine Type          vCPUs  Memory  Est. Cost/Month  Recommended For
--------------------------------------------------------------------------------
1) e2-micro            0.25   1 GB    ~$7-9           Testing only (may be slow)
2) e2-small            0.5    2 GB    ~$14-16         Light usage, few workflows
3) e2-medium           1      4 GB    ~$24-30         Recommended: Most users
4) e2-standard-2       2      8 GB    ~$49-60         Heavy usage, many workflows
5) e2-standard-4       4     16 GB    ~$97-120        Very heavy usage, complex workflows
6) n2-standard-2       2      8 GB    ~$73-90         Better performance than e2
7) n2-standard-4       4     16 GB    ~$146-180       High performance needs

Select machine type (1-7) [default=3]: 3

Recommendation guidelines:

  • e2-micro/small: Testing, personal projects, <5 workflows
  • e2-medium: Most users, <20 active workflows
  • e2-standard-2: Teams, 20-50 workflows, complex operations
  • e2-standard-4+: Heavy usage, 50+ workflows, data processing

2.5 Domain Name

Enter your domain or subdomain:

Enter the domain name for n8n (e.g., n8n.example.com): n8n.yourdomain.com

Tips:

  • Use a subdomain (e.g., n8n.yourdomain.com or automation.yourdomain.com)
  • Domain must be valid and you must control its DNS settings
  • The script validates domain format

2.6 Configuration Confirmation

Review your selections:

=========================================
Deployment Configuration:
=========================================
Project:       my-project
Region:        europe-west1
Zone:          europe-west1-b
Machine Type:  e2-medium
Domain:        n8n.yourdomain.com
=========================================

Continue with this configuration? (y/N): y

Step 3: Resource Provisioning

The script creates:

  1. ✅ Static IP address
  2. ✅ Firewall rules (ports 80, 443, 22)
  3. ✅ Compute Engine instance
  4. ✅ Displays your static IP
Reserving a static IP address...
Created: 34.22.180.114

Creating firewall rules...
Created: allow-web-traffic

Creating the Compute Engine instance...
Created: n8n-instance (e2-medium)

Step 4: DNS Configuration

Update your DNS A record:

-----------------------------------------------------
Action Required:
Please create a DNS A record for 'n8n.yourdomain.com' pointing to the IP address: 34.22.180.114
-----------------------------------------------------
Press [Enter] to continue after updating the DNS record...

How to create DNS A record:

Cloudflare
  1. Log in to Cloudflare
  2. Select your domain
  3. Go to DNS → Records
  4. Click "Add record"
  5. Type: A
  6. Name: n8n (or your subdomain)
  7. IPv4 address: 34.22.180.114 (your static IP)
  8. Proxy status: DNS only (gray cloud)
  9. Click "Save"
Google Domains
  1. Log in to Google Domains
  2. Select your domain
  3. Click "DNS" in the left menu
  4. Scroll to "Custom resource records"
  5. Name: n8n
  6. Type: A
  7. TTL: 3600
  8. Data: 34.22.180.114
  9. Click "Add"
Other DNS Providers

Create an A record with:

  • Type: A
  • Name/Host: n8n (or your subdomain)
  • Value/Points to: 34.22.180.114 (your static IP)
  • TTL: 3600 (or default)

Step 5: DNS Verification

The script automatically verifies DNS propagation:

Checking DNS propagation for n8n.yourdomain.com...
Attempt 1/10: Checking if n8n.yourdomain.com resolves to 34.22.180.114...
✓ DNS propagation confirmed! n8n.yourdomain.com resolves to 34.22.180.114

If DNS hasn't propagated:

  • The script retries up to 10 times (100 seconds total)
  • You can continue anyway or cancel to wait longer
  • DNS propagation can take 5-60 minutes depending on your provider

Step 6: Remote Configuration

The script automatically:

  1. ✅ Copies configuration files to the instance
  2. ✅ Installs Docker and Docker Compose
  3. ✅ Configures Caddy and n8n
  4. ✅ Starts the services
Copying setup files to the instance...
Executing the setup script on the instance...
Installing Docker...
Starting n8n and Caddy...

Step 7: Deployment Complete!

-----------------------------------------------------
Deployment complete!
You can now access your n8n instance at: https://n8n.yourdomain.com
-----------------------------------------------------

First time setup:

  1. Open https://n8n.yourdomain.com in your browser
  2. Create your admin account (email + password)
  3. Start creating workflows!

Managing Your Instance

SSH Access

Connect to your instance:

gcloud compute ssh n8n-instance --zone=europe-west1-b

Viewing Logs

# SSH into instance
gcloud compute ssh n8n-instance --zone=europe-west1-b

# Navigate to app directory
cd /opt/n8n

# View n8n logs
sg docker -c "docker compose logs -f n8n"

# View Caddy logs
sg docker -c "docker compose logs -f caddy"

# View all logs
sg docker -c "docker compose logs -f"

Updating n8n

# SSH into instance
gcloud compute ssh n8n-instance --zone=europe-west1-b

# Navigate to app directory
cd /opt/n8n

# Pull latest n8n image
sg docker -c "docker compose pull n8n"

# Recreate n8n container
sg docker -c "docker compose up -d --force-recreate n8n"

# Verify
sg docker -c "docker ps"

Restarting Services

# SSH into instance
cd /opt/n8n

# Restart all services
sg docker -c "docker compose restart"

# Restart only n8n
sg docker -c "docker compose restart n8n"

# Restart only Caddy
sg docker -c "docker compose restart caddy"

Checking Status

# View running containers
sg docker -c "docker ps"

# Check disk usage
df -h

# Check memory usage
free -h

# Check container stats
sg docker -c "docker stats"

Backup and Restore

Creating a Backup

# SSH into instance
gcloud compute ssh n8n-instance --zone=europe-west1-b

# Create backup directory
sudo mkdir -p /backups

# Stop n8n (optional but recommended for consistency)
cd /opt/n8n
sg docker -c "docker compose stop n8n"

# Create backup
sudo tar -czvf /backups/n8n_backup_$(date +%Y%m%d%H%M%S).tar.gz \
  -C /var/lib/docker/volumes/n8n-cloud-deploy_n8n_data/_data .

# Restart n8n
sg docker -c "docker compose start n8n"

# List backups
ls -lh /backups/

Downloading Backup to Local Machine

# From your local machine
gcloud compute scp n8n-instance:/backups/n8n_backup_*.tar.gz . --zone=europe-west1-b

Restoring from Backup

# Upload backup to instance (from local machine)
gcloud compute scp n8n_backup_*.tar.gz n8n-instance:~ --zone=europe-west1-b

# SSH into instance
gcloud compute ssh n8n-instance --zone=europe-west1-b

# Stop n8n
cd /opt/n8n
sg docker -c "docker compose stop n8n"

# Clear current data
sudo rm -rf /var/lib/docker/volumes/n8n-cloud-deploy_n8n_data/_data/*

# Extract backup
sudo tar -xzvf ~/n8n_backup_*.tar.gz \
  -C /var/lib/docker/volumes/n8n-cloud-deploy_n8n_data/_data

# Fix permissions
sudo chown -R 1000:1000 /var/lib/docker/volumes/n8n-cloud-deploy_n8n_data/_data

# Start n8n
sg docker -c "docker compose start n8n"

Automated Backups (Optional)

Create a cron job for daily backups:

# SSH into instance
gcloud compute ssh n8n-instance --zone=europe-west1-b

# Create backup script
sudo nano /usr/local/bin/backup-n8n.sh

Add this content:

#!/bin/bash
cd /opt/n8n
sg docker -c "docker compose stop n8n"
sudo tar -czvf /backups/n8n_backup_$(date +%Y%m%d).tar.gz \
  -C /var/lib/docker/volumes/n8n-cloud-deploy_n8n_data/_data .
sg docker -c "docker compose start n8n"
# Keep only last 7 backups
sudo find /backups -name "n8n_backup_*.tar.gz" -mtime +7 -delete

Make executable and add to cron:

sudo chmod +x /usr/local/bin/backup-n8n.sh
sudo crontab -e

# Add this line (daily backup at 2 AM)
0 2 * * * /usr/local/bin/backup-n8n.sh

Decommissioning

Interactive Cleanup

bash cleanup.sh

The script will:

  1. Detect existing resources
  2. Ask what to delete (instance, firewall, static IP)
  3. Show summary
  4. Require confirmation
  5. Delete selected resources

Example:

Delete Compute Engine instance 'n8n-instance'? (y/N): y
Delete firewall rule 'allow-web-traffic'? (y/N): n
Delete static IP 'n8n-static-ip'? (y/N): n

Manual Cleanup

# Delete instance
gcloud compute instances delete n8n-instance --zone=europe-west1-b

# Delete firewall rule (optional)
gcloud compute firewall-rules delete allow-web-traffic

# Delete static IP (optional)
gcloud compute addresses delete n8n-static-ip --region=europe-west1

Important: Don't forget to remove your DNS A record!

Troubleshooting

DNS Not Propagating

Problem: DNS doesn't resolve to the correct IP.

Solutions:

# Check DNS resolution
dig +short n8n.yourdomain.com @8.8.8.8

# Check with different DNS servers
dig +short n8n.yourdomain.com @1.1.1.1
dig +short n8n.yourdomain.com @8.8.4.4

# Wait 5-10 minutes and try again

SSL Certificate Not Issued

Problem: HTTPS not working, certificate errors.

Solutions:

# Check Caddy logs
gcloud compute ssh n8n-instance --zone=europe-west1-b
cd /opt/n8n
sg docker -c "docker compose logs caddy"

# Verify ports are open
curl -v http://n8n.yourdomain.com
curl -v https://n8n.yourdomain.com

# Restart Caddy
sg docker -c "docker compose restart caddy"

Cannot Access n8n Instance

Problem: Browser shows "Connection refused" or timeout.

Solutions:

# Verify instance is running
gcloud compute instances list

# Check containers are running
gcloud compute ssh n8n-instance --zone=europe-west1-b
sg docker -c "docker ps"

# Check firewall rules
gcloud compute firewall-rules describe allow-web-traffic

Out of Disk Space

Problem: n8n stops working, disk full errors.

Solutions:

# Check disk usage
gcloud compute ssh n8n-instance --zone=europe-west1-b
df -h

# Clean up Docker
sg docker -c "docker system prune -a"

# Resize disk (in GCP Console or via gcloud)

Performance Issues

Problem: n8n is slow or unresponsive.

Solutions:

  1. Upgrade to larger machine type
  2. Check resource usage: sg docker -c "docker stats"
  3. Optimize workflows
  4. Review and clean up old executions

Need More Help?

Next: Secure your deployment with SECURITY.md