Self-Hosted Guide

Everything you need to host Seogard on your own server.

Getting Started

Prerequisites: Docker and Docker Compose installed on your server.

  1. Clone the repo
    git clone https://github.com/seogard-software/seogard.git && cd seogard
  2. Copy and configure the environment file
    cp .env.example .env

    Edit .env — you must change:

    VariableDescription
    MONGO_PASSWORDMongoDB password — pick a strong one
    NUXT_JWT_SECRETJWT signing key — 64+ random characters
    NUXT_PUBLIC_APP_URLPublic URL of your instance (e.g. https://seo.mysite.com)
  3. Run
    docker compose -f docker-compose.self-hosted.yml up -d
  4. Open http://localhost:3000 and create your admin account

The first account created becomes the administrator (owner). Registration then closes automatically — subsequent members are added by invitation.

A single .env file for everything (web + crawler). MongoDB and Redis connections are handled automatically by Docker.

Architecture

Your server
WebDashboard + APIport 3000
WorkersPlaywright crawlerx2
MongoDBDatabase
RedisCrawl queue

The Web serves the dashboard and the API. The Workers crawl pages with Playwright (headless browser). Redis distributes pages to the workers. MongoDB stores the data.

Sizing

Each crawler worker uses ~1 GB of RAM. MongoDB needs a RAM cache to perform well. The rest (~2 GB) is shared between Redis, the web server and the OS.

Formula: MongoDB cache = server RAM - (workers × 1 GB) - 2 GB

Server RAMWorkersMongoDB cachePages you can monitor
4 GB11 GB~5 000
8 GB33 GB~15 000
16 GB86 GB~50 000
32 GB1515 GB~100 000+

The MongoDB cache defaults to 2 GB in the docker-compose. Adjust it to your server by editing docker-compose.self-hosted.yml → --wiredTigerCacheSizeGB X.

# Lancer avec 3 workers
WORKER_REPLICAS=3 docker compose -f docker-compose.self-hosted.yml up -d

Adjusting workers

Change the number of workers to match your server resources:

WORKER_REPLICAS=5 docker compose -f docker-compose.self-hosted.yml up -d

Or edit docker-compose.self-hosted.yml directly → replicas: 5

Email notifications

Optional — without email configuration, Seogard still works but sends no alerts and no password resets.

  1. Create a free account on resend.com (100 emails/day)
  2. Verify your domain in the Resend dashboard
  3. Add to your .env:
    RESEND_API_KEY=re_votre_cle_ici
    [email protected]
  4. Restart: docker compose -f docker-compose.self-hosted.yml restart web worker

OAuth login

Optional — without OAuth, users log in with email + password.

Add the keys to your .env to enable each provider:

Google
  1. Create an OAuth Client on Google Cloud Console
  2. Redirect URI : https://seogard.io/api/auth/oauth/google/callback
  3. GOOGLE_CLIENT_ID=... and GOOGLE_CLIENT_SECRET=...
Microsoft
  1. Create an app on Azure Portal → App registrations
  2. Redirect URI : https://seogard.io/api/auth/oauth/microsoft/callback
  3. MICROSOFT_CLIENT_ID=... and MICROSOFT_CLIENT_SECRET=...
GitHub
  1. Create an OAuth App on GitHub Developer Settings
  2. Callback URL : https://seogard.io/api/auth/oauth/github/callback
  3. GITHUB_CLIENT_ID=... and GITHUB_CLIENT_SECRET=...

Crawler whitelisting

If your sites are behind a WAF (Cloudflare, Akamai, etc.), you must whitelist your server's IP.

See the whitelisting guide

Updating

cd seogard
git pull
docker compose -f docker-compose.self-hosted.yml up --build -d

MongoDB data persists in a Docker volume. No data loss during an update.

License

Seogard is distributed under the Business Source License 1.1 (BSL). You can use it for free for internal use (monitoring your own sites). Using it as a competing commercial service is prohibited.

Each release automatically converts to Apache 2.0 after 3 years.

Read the full license

Backup

# Sauvegarder
docker exec seogard-mongo-1 mongodump --archive > backup-$(date +%Y%m%d).archive

# Restaurer
docker exec -i seogard-mongo-1 mongorestore --archive < backup.archive