Skip to content
Klutch.sh Docs

Deploying a SerpBear App

Introduction

SerpBear is an open-source SERP tracker that monitors keyword rankings across search engines. Deploying SerpBear with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample checks.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your SerpBear Dockerfile (GitHub is the only supported git source)
  • Optional: search engine API keys if you need authenticated providers

For onboarding, see the Quick Start.

Architecture and ports

  • SerpBear serves HTTP on internal port 3000. Choose HTTP traffic and set the internal port to 3000.
  • Persistent storage is recommended for the internal database and cached results.

Repository layout

serpbear/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally:

Terminal window
docker build -t serpbear-local .
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e DB_PATH=/app/data/serpbear.db \
  serpbear-local

Dockerfile for SerpBear (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM node:18-alpine


WORKDIR /app


COPY package*.json ./
RUN npm ci


COPY . .


ENV PORT=3000
ENV DB_PATH=/app/data/serpbear.db


EXPOSE 3000
CMD ["npm", "run", "start"]

Notes:

  • Pin Node to the version SerpBear supports; adjust if upstream changes.
  • Keep the Dockerfile at repo root; Docker selection is automatic in Klutch.sh.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=3000
  • DB_PATH=/app/data/serpbear.db
  • Optional: any provider API keys supported by SerpBear

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_NODE_VERSION=18
  • NIXPACKS_START_CMD=npm run start

Attach persistent volumes

Add storage in Klutch.sh (path and size only):

  • /app/data — SQLite database and cached results.

Ensure the path is writable inside the container.

Deploy SerpBear on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 3000.
  4. Add the environment variables above (port, DB path, and any provider keys).
  5. Attach a volume at /app/data sized for your database and history.
  6. Deploy. Your app will be reachable at https://example-app.klutch.sh.

Sample checks

Landing page:

Terminal window
curl -I https://example-app.klutch.sh

If SerpBear exposes a health endpoint (replace if different):

Terminal window
curl -I https://example-app.klutch.sh/health

Health checks and production tips

  • Add an HTTP readiness probe to / or your health endpoint.
  • Keep API keys (if used) in Klutch.sh secrets; rotate regularly.
  • Pin image/Node versions and test upgrades in staging before production rollout.
  • Monitor /app/data volume usage; resize proactively as history grows.

SerpBear on Klutch.sh delivers reproducible Docker builds, managed secrets, and persistent tracking data—without extra YAML or CI steps. Configure ports, env vars, and storage, then start tracking SERP performance.