Self-Hosted Lead Generation: Complete Setup Guide with Docker

This guide walks through the entire process of self-hosting Cold Scout — the open-source AI lead generation pipeline — on your own machine or VPS. By the end, you will have a running web dashboard, a FastAPI backend, and an AI pipeline that can discover leads from Google Maps and draft personalized cold emails.

What you will need

• A machine — your laptop, or a VPS with at least 1 GB RAM and Docker installed.
• A Google Cloud project with the Places API enabled. Free tier is more than enough to get started.
• A Groq account (free) for AI inference.
• A Brevo (Sendinblue) account (free up to 300 emails/day) for sending.
• A Supabase project (free) — Cold Scout uses Supabase Auth + Postgres.

Step 1 — Clone the repository

git clone https://github.com/colddsam/coldscout.git
cd coldscout

The repo includes a docker-compose.yml that orchestrates the backend, frontend, and the APScheduler worker.

Step 2 — Provision API keys

2.1 Google Places API

1. Go to the Google Cloud Console and create a project (or pick an existing one).
2. Enable the Places API (New) from the API Library.
3. Create an API key from APIs & Services → Credentials.
4. Restrict the key to the Places API to limit blast radius if it leaks.

2.2 Groq

1. Sign up at console.groq.com.
2. Create an API key — Cold Scout calls Llama 3.3 70B and Llama 3.1 8B.

2.3 Brevo (Sendinblue)

1. Sign up at brevo.com — confirm the email associated with the account.
2. Generate an SMTP key from the SMTP & API page.
3. Verify a sending domain (recommended). DKIM and SPF take effect within minutes.

2.4 Supabase

1. Create a new Supabase project (the free tier works).
2. Copy the database URL, the anon key, and the service-role key.
3. Run the SQL migrations from sqlcommands/ against the project.

Step 3 — Configure environment variables

Copy the example file and fill in the keys you just created:

cp .env.example .env

The fields you must set:

# Database
DATABASE_URL=postgresql+asyncpg://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NAME]
SUPABASE_URL=https://[PROJECT].supabase.co
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

# AI
GROQ_API_KEY=...

# Discovery
GOOGLE_PLACES_API_KEY=...

# Outreach
BREVO_SMTP_HOST=smtp-relay.brevo.com
BREVO_SMTP_USER=...
BREVO_SMTP_PASSWORD=...
SENDER_EMAIL=hello@yourdomain.com
SENDER_NAME=Your Name

# Misc
SECRET_KEY=$(openssl rand -hex 32)

Step 4 — Run with Docker Compose

docker compose up --build

On a fresh machine the first build pulls about 1 GB of layers. After that, starts are fast. The default ports:

• Frontend dashboard — http://localhost:5173
• FastAPI backend — http://localhost:8000
• API docs (Swagger UI) — http://localhost:8000/docs

Step 5 — Create your account

Open the dashboard, click Sign up, and verify the email. The first user is automatically promoted to the freelancer role with full access.

Step 6 — Define your first ICP

From the dashboard, go to Discovery → New target. The fields:

• Target type — e.g. "independent restaurants".
• Geography — e.g. "Bengaluru, India".
• Minimum rating — typical 4.0+.
• Minimum reviews — typical 100+ to filter out fake/empty listings.

Cold Scout will run the discovery in the background and stream results into the Leads tab.

Step 7 — Run a qualification pass

Once leads land, go to Pipeline → Qualification and click Run. Behind the scenes the worker:

1. Fetches each lead's website and extracts metadata.
2. Calls Groq with the qualification prompt and the website context.
3. Stores an intent score (0–100) and a one-line rationale per lead.
4. Auto-tags each lead as hot / warm / cold.

Step 8 — Send your first cold email

Pick a hot lead, click Generate email, and review the draft. The first draft is rarely the final draft — your edits become signal that the prompt-tuner can use later.

When you're happy, click Send. The backend hands the message to Brevo over SMTP and stores the message-id for reply tracking.

Going to production

• Move the database off Docker — point DATABASE_URL at managed Postgres (Supabase, Neon, Render, RDS). Backups become someone else's problem.
• Put a real domain in front of the frontend with HTTPS terminated by Nginx, Caddy, or a CDN. The repo includes an nginx.conf with security headers already set.
• Pin the Docker image versions in docker-compose.yml instead of rebuilding from HEAD. Predictable deploys, predictable bugs.
• Enable Brevo's domain authentication (DKIM + DMARC) so deliverability isn't gated by IP reputation alone.

Troubleshooting

• Discovery returns 0 results — your Places API key is probably restricted to a different referrer. Check the Cloud Console.
• Qualification stalls — Groq rate limit. Drop concurrency in backend/app/workers/qualification.py or upgrade your Groq tier.
• Outbound mail bounces — Brevo requires SPF for theSENDER_EMAIL domain. Add the TXT record they show you and wait 10 minutes.

What you saved by self-hosting

Apollo at $50/mo per seat, Outreach at $130/mo per seat, Instantly at $30/mo plus list-building. Cold Scout self-hosted runs on the free tiers of every underlying service — your monthly bill is zero until you exceed the free quotas. That is the whole point of an open-source alternative.