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

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 we suggest the smallest plan and an 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.

Plan specs and prices below are from our Linux VPS plans page as of October 2026.

What you run	Plan	Specs	Price
SerpBear only	Basic	1 vCore, 3 GB RAM, 200 GB HDD	$19/mo
SerpBear plus n8n or SearXNG	Essential	2 vCores, 4 GB RAM, 400 GB HDD	$25/mo
The above plus a headless browser crawler	Comfort	4 vCores, 6 GB RAM	$35/mo

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

Only need rank tracking? Order the Basic Linux VPS at $19 per month, or compare all four Linux VPS plans. VPS orders are usually delivered within 15 minutes and come with a 3-day money-back guarantee.

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?

Log in over SSH as root, update the system and run Docker’s install script. Docker Compose comes with it.

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.

1. Create a project in Google Cloud and enable the Google Search Console API for it.
2. 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.
3. 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.
4. 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 the Essential plan with 4 GB RAM. Our guide to the best VPS for SEO tools and automation covers sizing for a full stack.

Is rank tracking allowed on a KwikServer VPS?

Yes. Checking where your own and your clients’ sites rank is a normal use. Tools for fake traffic, click manipulation, automated link spam or mass account creation are not allowed.

Start with the smallest plan and measure

SerpBear is light because the scraping happens elsewhere, so a Basic Linux VPS is the place to start. Install Docker, bring up the container, add Nginx and SSL, connect a scraper, and set up the weekly backup before you add your hundredth keyword. See the Linux VPS plans and pricing, or ask our team which plan fits the tools you want to run alongside it.