FlashPanel

Deploy SerpBear ​

SerpBear is an open source tool for tracking keyword rankings on Google. This guide runs SerpBear with Docker Compose on port 4444 of the server, while the website on FlashPanel forwards requests for the domain (for example serpbear.domain.com) to that port.

Prerequisites ​

  • Server connected to FlashPanel
  • Domain DNS pointed to the server's IP

Step 1: Install Docker ​

Go to the server management page, click the Apps menu, select the Not Installed tab, find Docker, then click Install. See Applications for details.

Step 2: Create a Website ​

  1. Go to the server management page, click the Sites menu in the sidebar, then click the New Site button
  2. Enter the Domain Name (e.g., serpbear.domain.com)
  3. Enter the Proxy Port: 4444 (you can choose another free port)
  4. Click Create Site

Step 3: Install SSL ​

On the site management page, click the SSL menu and install a certificate for the domain. See SSL.

Step 4: Create the docker-compose.yaml File ​

Open Terminal on the server's overview page (logged in as root), create a directory for SerpBear and open the configuration file:

bash
mkdir -p /root/serpbear
cd /root/serpbear
nano docker-compose.yaml

You can also use File Manager on the server's overview page to create the file /root/serpbear/docker-compose.yaml.

Paste the following content into the file and save it:

yaml
services:
    app:
        image: towfiqi/serpbear
        restart: unless-stopped
        ports:
            - 127.0.0.1:4444:3000
        environment:
            - USER=admin
            - PASSWORD=0123456789
            - SECRET=4715aed3216f7b0a38e6b534a958362654e96d10fbc04700770d572af3dce43625dd
            - APIKEY=5saedXklbslhnapihe2pihp3pih4fdnakhjwq5
            - SESSION_DURATION=24
            - NEXT_PUBLIC_APP_URL=https://serpbear.domain.com
        volumes:
            - serpbear_appdata:/app/data
volumes:
    serpbear_appdata:

Notes on the highlighted lines:

  • 127.0.0.1:4444:3000: 3000 is SerpBear's fixed port inside the container and should not be changed. 4444 is the Proxy Port of the website created in step 2. The 127.0.0.1: part keeps port 4444 open only inside the server: Docker adds its own network rules and bypasses the UFW firewall, so with just 4444:3000 the port would be reachable directly from the Internet even if the firewall does not open it
  • USER: the username for logging in to SerpBear, for example admin
  • PASSWORD: the login password. Use a strong password instead of the sample value 0123456789
  • SECRET: the secret key used to encrypt third-party API keys and passwords
  • APIKEY: the key used to access SerpBear's API
  • SESSION_DURATION: duration (in hours) of the login session, for example 24
  • NEXT_PUBLIC_APP_URL: the URL used to access SerpBear, which is the domain of the website created in step 2

TIP

Do not use the sample values for SECRET and APIKEY. Generate random strings with openssl rand -hex 32 and paste them in.

Step 5: Start SerpBear ​

In the server's Terminal, run:

bash
cd /root/serpbear
docker compose up -d

Verify the Result ​

  1. Run docker compose ps in /root/serpbear; the app container shows the running status
  2. Visit https://serpbear.domain.com and log in with the USER/PASSWORD you configured

Updating the Configuration or Version ​

After editing docker-compose.yaml, run the command below again. Docker Compose recreates the container with the new configuration (docker restart does not apply changes made to docker-compose.yaml):

bash
cd /root/serpbear
docker compose up -d

To update SerpBear to a new version, pull the new image and recreate the container. Your data is kept in the serpbear_appdata volume:

bash
cd /root/serpbear
docker compose pull
docker compose up -d

Troubleshooting ​

502 Bad Gateway ​

  1. Check that the container is running: docker compose ps
  2. Make sure port 4444 in docker-compose.yaml matches the website's Proxy Port
  3. View the container logs: docker compose logs -f app

Cannot Log In ​

Double-check USER, PASSWORD and NEXT_PUBLIC_APP_URL (it must be the correct domain, including https://), then run docker compose up -d again.