DEV Community: Kwik Server

How to Self-Host n8n with Docker Compose and Nginx (2026)

Kwik Server — Wed, 07 Oct 2026 13:53:14 +0000

To self-host n8n with Docker Compose and Nginx, run the n8n container bound to localhost on port 5678, put an Nginx server block with WebSocket headers in front of it, and add a Let’s Encrypt certificate. Then set WEBHOOK_URL and N8N_PROXY_HOPS=1 so webhooks and the editor work behind the proxy.

n8n’s own Compose guide uses Traefik, and its other server guides use Caddy. This guide is for people who already run Nginx on the server, or want to, and need the proxy settings that those guides leave out. It also covers running n8n next to another tool on the same server, backups and the errors a proxy setup tends to cause.

Tested on Ubuntu 24.04.5 LTS with n8n 2.42.4 in October 2026.

What do you need to self-host n8n?

A Linux VPS with root SSH access, a subdomain pointed at it, and about half an hour.

A VPS running Ubuntu. The commands below are written for Ubuntu 24.04 and work the same way on Debian.
A subdomain. Create an A record such as n8n.yourdomain.com that points to the server’s IP address. Do this first so DNS has updated by the time you request the certificate.
Some comfort with a terminal. n8n’s docs recommend self-hosting for people who are used to managing servers, and point everyone else to n8n Cloud. That is fair advice. You are responsible for updates, backups and security.

This guide installs n8n by itself. It does not include the separate sandbox stack that n8n’s newer Compose guide adds for its AI Assistant, which needs more memory and a privileged container.

What size VPS does n8n need?

A small one. n8n’s Hetzner guide says a small CPX11 instance is enough for most usage, and suggests 4 GB RAM and 2 vCPU if you add the n8n Assistant. What grows memory use in practice is the size of the data your workflows handle and how many run at once.

On our test server, which has 4 GB of RAM, n8n used about 353 MB of memory at idle, or 9% of the total. SerpBear was running on the same server at the time, and the two containers together used about 476 MB, roughly 12%.

How do you set up n8n with Docker Compose?

Install Docker, create a project folder with a .env file and a compose.yaml file, and start the container. The Compose file below is n8n’s official one with the Traefik service and labels removed and one variable added.

Step 1: Install Docker

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
docker --version
docker compose version

Skip this if Docker is already on the server.

Step 2: Create the project folder

mkdir -p /opt/n8n/local-files && cd /opt/n8n
chown 1000:1000 local-files

The local-files folder is shared with the container at /files, for workflows that read or write files on disk. The chown matters when you work as root: n8n runs inside the container as user ID 1000 and cannot write to a folder that root owns.

Step 3: Create the .env file

nano .env

DOMAIN_NAME=yourdomain.com
SUBDOMAIN=n8n
GENERIC_TIMEZONE=Europe/Berlin

Replace yourdomain.com with your real domain before you save. We left the placeholder in on our own test run. n8n still starts with it, but it builds its webhook addresses from these two values, so every webhook URL would point at a domain you do not own.

Set the timezone to your own as well. n8n uses it for schedule triggers, and the default is New York if you leave it out.

Step 4: Create the compose.yaml file

nano compose.yaml

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/
      - N8N_PROXY_HOPS=1
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${GENERIC_TIMEZONE}
      - N8N_RESTRICT_FILE_ACCESS_TO=/files
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:

The port is bound to 127.0.0.1, as in the official file. Ports that Docker publishes skip UFW rules, so binding to localhost is what keeps port 5678 off the public internet. Only Nginx on the same server can reach it.

Step 5: Start n8n

docker compose up -d
docker compose ps
docker compose logs -f n8n

Press Ctrl+C to leave the logs. Do not open n8n in a browser yet. Set up Nginx and SSL first.

How do you put n8n behind Nginx with SSL?

Create an Nginx server block that proxies to port 5678 with WebSocket support, then let Certbot add the certificate.

apt install nginx -y
nano /etc/nginx/sites-available/n8n

server {
    listen 80;
    server_name n8n.yourdomain.com;

    client_max_body_size 16m;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Change server_name to your own subdomain before you go on. If it does not match the address you open in the browser, Nginx serves its default “Welcome to nginx” page instead of n8n. We hit exactly that on our test run.

Enable the site and add the certificate:

ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx
apt install certbot python3-certbot-nginx -y
certbot --nginx -d n8n.yourdomain.com --redirect
certbot renew --dry-run

If the firewall is not on yet, allow SSH before you enable it:

ufw allow ssh
ufw allow 'Nginx Full'
ufw enable

Now open https://n8n.yourdomain.com and create the owner account straight away. The first person to reach a new n8n instance gets to create that account, so do not leave it sitting unclaimed.

Which settings stop webhooks and the editor breaking behind a proxy?

Four of them. n8n’s docs on webhook URLs behind a reverse proxy cover the first three, and the fourth is on the Nginx side.

Setting	Where	What goes wrong without it
`WEBHOOK_URL`	compose.yaml	n8n builds webhook URLs from its internal host and port, so they point at port 5678 and outside services cannot reach them
`N8N_PROXY_HOPS=1`	compose.yaml	n8n does not trust the forwarded headers, so it sees every request as coming from the proxy
`X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto`	Nginx	n8n cannot tell the visitor’s address or that the original request was HTTPS
`Upgrade` and `Connection` headers	Nginx	The editor cannot hold its live connection and shows “Connection lost”

Two Nginx lines in our config are choices you may want to change. client_max_body_size 16m matches n8n’s default payload limit of 16 MiB, set by N8N_PAYLOAD_SIZE_MAX. Nginx’s own default of 1 MB would reject larger webhook bodies and file uploads first. proxy_read_timeout 3600s keeps long-running requests and the editor connection from being cut after Nginx’s default 60 seconds.

After changing anything in compose.yaml or .env, apply it with docker compose up -d. A plain restart does not pick up new environment values.

To check the whole chain, add a Webhook node, click Listen for test event, and open its Test URL from another device. On our test server the request showed up in the editor straight away with x-forwarded-proto: https, the right x-forwarded-host and the caller’s real IP address in x-forwarded-for. If the editor receives the event, the WebSocket connection is working too.

Can n8n and SerpBear run on the same server?

Yes. Each runs in its own container on its own localhost port, and Nginx routes by hostname. Our test server runs both.

If you followed our guide to install SerpBear on a VPS, you already have Nginx, Certbot and the firewall in place. Skip those install lines above, add the n8n server block as a second file in sites-available, and run Certbot for the new subdomain. SerpBear stays on port 3000 and n8n on 5678, each in its own folder under /opt with its own Compose file, so updating one does not touch the other.

The pairing is useful for more than saving a server. SerpBear has an API, so an n8n workflow can pull keyword positions on a schedule and send rank changes to Slack, email or a spreadsheet.

How do you back up and update n8n?

Back up the n8n_data volume, and update with three Compose commands.

Back up the data volume

n8n’s docs describe the n8n_data volume as where it saves its SQLite database file and encryption key. The key is what decrypts your saved credentials. If you lose it, the workflows can be rebuilt but every stored credential has to be entered again, so back up the whole volume, not just an export of workflows.

Compose prefixes the volume with the folder name, so it is called n8n_n8n_data if you used /opt/n8n. Confirm with docker volume ls. Save this as /root/n8n-backup.sh:

#!/bin/sh
mkdir -p /root/backups
cd /opt/n8n
docker compose stop
docker run --rm -v n8n_n8n_data:/data -v /root/backups:/backup alpine tar czf /backup/n8n-$(date +%F).tar.gz -C /data .
docker compose start

chmod +x /root/n8n-backup.sh

Schedule it with crontab -e, for example weekly at 03:30 on Sunday:

30 3 * * 0 /root/n8n-backup.sh

n8n is stopped for a few seconds while the archive is made, so pick a time when no workflow is due. Copy the archives off the server with scp or rsync.

Update n8n

n8n’s docs say a new minor version is released most weeks. These are the update steps from the docs:

cd /opt/n8n
docker compose pull
docker compose down
docker compose up -d

Take a backup first. If you would rather choose when you upgrade, pin a version in compose.yaml, for example image: n8nio/n8n:2.42.4, the version we tested. Change the tag when you are ready to move.

What are the common problems with n8n behind Nginx?

Nearly all of them trace back to a placeholder, a missing header or a missing variable.

The “Welcome to nginx” page instead of n8n. The server_name line still has the placeholder or does not match your subdomain. Fix it, then run nginx -t and systemctl reload nginx.
“Connection lost” in the editor. The Upgrade and Connection headers or proxy_http_version 1.1 are missing from the Nginx block. Check that Certbot’s edits left them in place.
Webhook URLs show the wrong domain, port 5678 or http. The .env values are wrong, WEBHOOK_URL is not set, or the container was not recreated. Fix the values and run docker compose up -d.
A secure cookie warning on the login page. You opened n8n over plain HTTP or by IP address. Use the HTTPS subdomain.
413 Request Entity Too Large. Raise client_max_body_size in Nginx. For bodies above 16 MiB, raise N8N_PAYLOAD_SIZE_MAX in compose.yaml as well.
Schedules fire at the wrong hour. GENERIC_TIMEZONE is unset or wrong.
Cannot write to /files. The local-files folder is owned by root. Run chown 1000:1000 /opt/n8n/local-files.
502 Bad Gateway. Nginx is up but n8n is still starting or has stopped. Check docker compose ps and the logs.

Frequently asked questions

Is self-hosted n8n free?

The Community Edition costs nothing to run for your own business, and you pay only for the server. n8n is released under the Sustainable Use License, which is source-available and not an open-source license. Read it before you offer n8n to others as a hosted service.

Do I need PostgreSQL to run n8n?

No. n8n’s Compose guide uses the built-in SQLite database, which is what this guide sets up. PostgreSQL is supported and is the usual step up when workloads get heavy.

Why use Nginx when n8n’s docs use Traefik?

Either works. Nginx makes sense when it is already on the server for other sites or tools, because one proxy then handles every subdomain and certificate. If n8n is the only thing on the server, the official Traefik file is less to set up.

Can I open n8n by IP address without a domain?

Not with this setup, and we would not expose it that way. For a private test, tunnel the port over SSH with ssh -L 5678:localhost:5678 root@your-server-ip and browse to http://localhost:5678.

How much RAM does n8n use?

On our test server n8n 2.42.4 used about 353 MB at idle. Memory rises with the amount of data a workflow processes and the number of workflows running at once.

What else is worth running on the same VPS?

A rank tracker, a metasearch engine and a reporting dashboard all sit comfortably beside n8n. Our guide to the best VPS for SEO tools and automation lists what each tool needs.

Originally published on the KwikServer tutorials blog.

How to Install SerpBear on a VPS with Docker (2026)

Kwik Server — Wed, 07 Oct 2026 08:58:48 +0000

To install SerpBear on a VPS, install Docker, create a .env file and a docker-compose.yaml file, then run docker compose up -d. Put Nginx with a Let’s Encrypt certificate in front of it, log in, and connect a scraping API such as ScrapingRobot or Serper.dev. We suggest starting on a 1 vCore, 3 GB RAM server.

This guide is for SEO freelancers and agencies who want their own rank tracker without per-keyword fees. It goes past the install command and covers the domain and SSL setup, the scraper, Search Console, backups, updates and the errors you are most likely to hit.

Tested on Ubuntu 24.04.5 LTS with SerpBear v3.1.0 in October 2026.

What is SerpBear and why self-host it?

SerpBear is an open-source rank tracker that records where your domains appear in Google for the keywords you choose. You run it on your own server, so the keyword history stays with you and there is no per-keyword or per-seat charge from the software.

It has email notifications for position changes, a Google Search Console integration and its own API for reporting tools. One thing to know before you start: SerpBear does not query Google from your server. Its getting started guide says you need a third-party scraping account or proxy IPs, because scraping Google directly gets an IP banned. Your VPS runs the dashboard, the schedule and the database. The scraping service fetches the results.

If you only track a handful of keywords for one site, you can run SerpBear on your own PC for free. The docs note the limits of that: no access from your phone and no API for reporting apps. A VPS is for when you want it running every day without your laptop being open.

What size VPS does SerpBear need?

SerpBear publishes no minimum hardware figure in its README or docs. Because the scraping happens on someone else’s infrastructure, the server only runs a Node.js app, a scheduler and a small database, so a small server is enough to start, and you can upgrade if memory runs short.

On our test install, a 4 GB server running Ubuntu 24.04.5 LTS, the SerpBear container used between 112 MB and 144 MB of memory across our readings, which is under 4% of the server’s RAM. A manual keyword refresh added about 20 MB while it ran. The image takes 461 MB on disk.

HDD storage is fine for a rank tracker. Server location does not change your ranking data, since you set the country for each keyword inside SerpBear. Pick the location closest to you so the dashboard loads quickly.

What do you need before you install SerpBear on a VPS?

Three things: a Linux VPS with root SSH access, a domain or subdomain, and a scraping API key.

A VPS running Ubuntu. The commands below are written for Ubuntu and work the same way on Debian.
A subdomain pointed at the server. Create an A record such as serpbear.yourdomain.com that points to your VPS IP address. Do this first so DNS has time to update before you request the SSL certificate.
A scraping API key. The SerpBear docs list ScrapingRobot (5,000 free requests per month) and Serper.dev (2,500 free requests) as places to start.

How do you install Docker on Ubuntu?

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh

Check that both are installed:

docker --version
docker compose version

How do you set up SerpBear with Docker Compose?

Create a folder, add two files and start the container. The files below follow the official deployment guide with two changes, both explained underneath.

Step 1: Create the folder and generate two keys

mkdir -p /opt/serpbear && cd /opt/serpbear
openssl rand -hex 34
openssl rand -hex 20

The first value is your SECRET, which SerpBear uses to encrypt the API keys and passwords you save in it. The second is your APIKEY for SerpBear’s own API. Copy both.

Step 2: Create the .env file

nano .env

SERPBEAR_USER=admin
PASSWORD=choose-a-long-password
SECRET=paste-the-first-value
APIKEY=paste-the-second-value
SESSION_DURATION=24
NEXT_PUBLIC_APP_URL=https://serpbear.yourdomain.com

Then restrict who can read it:

chmod 600 .env

SESSION_DURATION is how many hours a login lasts. NEXT_PUBLIC_APP_URL must be the exact address you will open in the browser, including https://.

Step 3: Create the docker-compose.yaml file

nano docker-compose.yaml

services:
  app:
    image: towfiqi/serpbear:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - USER_NAME=${SERPBEAR_USER:-admin}
      - PASSWORD=${PASSWORD}
      - SECRET=${SECRET}
      - APIKEY=${APIKEY}
      - SESSION_DURATION=${SESSION_DURATION:-24}
      - NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
    volumes:
      - serpbear_data:/app/data
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  serpbear_data:

The two changes from the official file:

The username variable is called SERPBEAR_USER, not USER. A Linux shell already has a USER variable set to your login name, and Docker Compose reads the shell before it reads .env. If you run the official file as root, your SerpBear username can end up as root instead of admin.
The port is bound to 127.0.0.1. Ports that Docker publishes skip UFW rules, so a plain 3000:3000 leaves the login page open to the internet over unencrypted HTTP. Binding to localhost means only Nginx on the same server can reach it.

Step 4: Start SerpBear

docker compose up -d
docker compose ps
docker compose logs -f

Wait until docker compose ps shows the container as healthy. Press Ctrl+C to leave the logs. The container keeps running.

How do you add a domain, Nginx and SSL?

Install Nginx as a reverse proxy in front of port 3000, then let Certbot add a free Let’s Encrypt certificate. This is the Nginx option from the SerpBear docs.

apt install nginx -y
nano /etc/nginx/sites-available/serpbear

server {
    listen 80;
    server_name serpbear.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site and check the config:

ln -s /etc/nginx/sites-available/serpbear /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

Add the certificate and confirm renewal works:

apt install certbot python3-certbot-nginx -y
certbot --nginx -d serpbear.yourdomain.com
certbot renew --dry-run

Certbot edits the Nginx config to redirect HTTP to HTTPS. Last, turn on the firewall. Allow SSH before you enable it, or you will lock yourself out.

ufw allow ssh
ufw allow 'Nginx Full'
ufw enable

Open https://serpbear.yourdomain.com, log in with the username and password from your .env file, and add your first domain when SerpBear asks for it.

Which scraper service should you connect?

Start with a free tier from ScrapingRobot or Serper.dev, and move to a paid service or proxies when you outgrow it. Until a scraper is connected, SerpBear cannot fetch any positions.

We used Scraping Robot for our test in October 2026 and it worked. Its scraping API is now provided through Rayobyte, so you create the account and copy the API key there. SerpBear’s README currently lists scrapingrobot.com as no longer working, so if your keywords stay empty with it, switch to Serper.dev. Check the current free allowance on the provider’s site before you plan around the figures in the SerpBear docs.

In SerpBear, open Settings from the top right corner, choose the service, paste your API key and save. The docs say to refresh the page afterwards. Then click Add Keyword, enter your keywords, and choose the country and device for each.

To estimate what you need, count one request per keyword per day. At that rate 100 keywords use about 3,000 requests a month, which fits inside ScrapingRobot’s 5,000 free requests. Desktop and mobile are tracked as separate keywords, so tracking both doubles the count. SerpBear’s integrations page lists the other supported services.

You can also use your own proxies. Select Proxy in the scraper list and enter them as http://username:password@IP_ADDRESS:PORT. The docs say datacenter IPs work and residential IPs are not required.

For position-change emails, add SMTP details in the same Settings panel.

How do you connect Google Search Console?

Create a Google Cloud service account, give it access to your Search Console property, and paste its two credentials into SerpBear. This adds real clicks, impressions and average position next to each tracked keyword.

Create a project in Google Cloud and enable the Google Search Console API for it.
Create a service account in that project, open Manage Keys, and add a JSON key. The downloaded file holds the client_email and private_key values.
In Search Console, open Settings, then Users and permissions, and add the client_email address as a user with Full permission. Repeat this for every property you want in SerpBear.
In SerpBear, open Settings, go to the Search Console tab, and paste both values. They apply to all your domains.

The full walkthrough with screenshots is in the SerpBear Search Console guide. We prefer pasting the credentials in the Settings screen over putting the private key in .env, because a multi-line key is easy to break in an environment file.

How do you back up and update SerpBear?

Everything SerpBear stores lives in one Docker volume, so a backup is a single archive of that volume and an update is two commands.

Back up the data volume

Compose prefixes the volume with the folder name, so it is called serpbear_serpbear_data if you used /opt/serpbear. Confirm with docker volume ls. Save this as /root/serpbear-backup.sh:

#!/bin/sh
mkdir -p /root/backups
cd /opt/serpbear
docker compose stop
docker run --rm -v serpbear_serpbear_data:/data -v /root/backups:/backup alpine tar czf /backup/serpbear-$(date +%F).tar.gz -C /data .
docker compose start

Make it executable and schedule it weekly with crontab -e:

chmod +x /root/serpbear-backup.sh
0 3 * * 0 /root/serpbear-backup.sh

The script stops SerpBear for a few seconds so the database is not copied mid-write. A backup that sits on the same server does not protect you from losing that server, so copy the archives somewhere else with scp or rsync.

Restore a backup

cd /opt/serpbear
docker compose down
docker run --rm -v serpbear_serpbear_data:/data -v /root/backups:/backup alpine sh -c "rm -rf /data/* && tar xzf /backup/serpbear-YYYY-MM-DD.tar.gz -C /data"
docker compose up -d

The same steps move SerpBear to a new server: install Docker, copy over the folder and the archive, and restore.

Update SerpBear

cd /opt/serpbear
docker compose pull
docker compose up -d
docker image prune -f

Your data stays in the volume through updates. Take a backup first anyway.

What are the common SerpBear install problems?

Most problems come from the environment file, the scraper settings or DNS.

Login fails with the right password. Run docker compose config | grep USER_NAME to see the username the container received. If it shows your Linux login name, you used USER in the compose file. Rename the variable as shown above and run docker compose up -d again.
Password or secret looks cut off. Compose treats $ in .env values as the start of a variable. Avoid $ in the password, or wrap the value in single quotes.
502 Bad Gateway. Nginx is up but SerpBear is not. Check docker compose ps and docker compose logs. Give the container a little time after a start or update.
Certbot cannot issue a certificate. The A record does not point to this server yet, or port 80 is blocked. Check with dig +short serpbear.yourdomain.com.
Keywords never get a position. No scraper is saved, the API key is wrong, or the free quota has run out. Recheck Settings and refresh the page.
Search Console returns “Forbidden”. The docs give two causes: the Search Console API is not enabled in the Google Cloud project, or the property type chosen in SerpBear (Domain or URL) does not match the property in Search Console.
Site thumbnails stop loading. SerpBear fetches them through a shared thum.io key limited to 1,000 a month. Create a free thum.io account and set your own key in the SCREENSHOT_API variable.

Frequently asked questions

Is SerpBear free?

The software is free and open source under the MIT license. Your costs are the server it runs on and, once you pass a free tier, the scraping API or proxies it uses to read Google results.

How many keywords can SerpBear track?

SerpBear sets no limit on domains or keywords. The practical limit is your scraping quota, since each keyword check uses a request.

Does SerpBear need proxies?

It needs either a scraping API or proxies. Most people start with an API key from ScrapingRobot or Serper.dev because there is nothing to manage. If you choose proxies, the docs say datacenter IPs are enough.

Can I run SerpBear without a domain name?

Yes. With the setup in this guide the app listens only on the server itself, so open an SSH tunnel with ssh -L 3000:localhost:3000 root@your-server-ip, set NEXT_PUBLIC_APP_URL to http://localhost:3000 and browse to that address. A subdomain with SSL is better for a team or for mobile access.

Can SerpBear share a VPS with n8n or other tools?

Yes. Each tool runs in its own container on its own port behind the same Nginx. For SerpBear plus a workflow tool we suggest a server with 4 GB RAM. Our guide to the best VPS for SEO tools and automation covers sizing for a full stack.

Originally published on the KwikServer tutorials blog.