Skip to main content
Waterline’s self-hosted option lets you run the full stack on your own infrastructure using Docker Compose. You bring your own LLM API keys and GitHub OAuth app — Waterline handles the rest. This guide walks you from a fresh clone to your first analyzed ticket.

​
Prerequisites

Before you begin, make sure you have:
  • Docker and Docker Compose installed
  • An OpenAI API key — required for embeddings (text-embedding-3-small)
  • At least one LLM provider: an Anthropic API key, an OpenAI API key, or Ollama running locally
  • A GitHub OAuth app for repository connection (create one at github.com/settings/developers)
  • A Jira OAuth app or API token if you plan to use Jira (create one at developer.atlassian.com)
If you only have one LLM provider, you can use it for everything. Set LLM_PROVIDER, ANALYSIS_LLM_PROVIDER, and SYMBOL_LLM_PROVIDER all to the same value — Waterline will route all tasks to that single provider.

​
Setup

1

Clone the repository and run setup

Clone the Waterline repository and run make setup to create your .env file:
git clone https://github.com/danfranco3/waterline.git
cd waterline
make setup
make setup copies .env.example to .env. Open .env in your editor before continuing.
2

Configure your .env file

At minimum, set the following variables. The comments explain what each does.
# Backend — use "postgres" for fully local Docker Compose
BACKEND=postgres
DATABASE_URL=postgresql://waterline:waterline@postgres:5432/waterline
JWT_SECRET=change-me-to-any-random-string-at-least-32-chars

# LLM — summary model (high quality, used for indexing)
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# LLM — analysis model (cheaper, used for relevance scoring)
ANALYSIS_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
ANALYSIS_OPENAI_MODEL=gpt-4o-mini

# LLM — symbol summary model (cheapest, high volume)
SYMBOL_LLM_PROVIDER=anthropic
SYMBOL_ANTHROPIC_MODEL=claude-haiku-4-5-20251001

# Embeddings — OpenAI only
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small

# GitHub OAuth app credentials
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_REDIRECT_URI=http://localhost:8000/api/connect/github/callback

# Jira OAuth app credentials (skip if using GitHub Issues only)
JIRA_CLIENT_ID=your-jira-client-id
JIRA_CLIENT_SECRET=your-jira-client-secret
JIRA_REDIRECT_URI=http://localhost:8000/api/connect/jira/callback

# Domain
DOMAIN=localhost
FRONTEND_URL=http://localhost:3001
API_BASE_URL=http://localhost:8000
Set JWT_SECRET to a random string of at least 32 characters before starting. You can generate one with openssl rand -hex 32.
3

Start the stack

Start all services with:
make dev
This starts four containers:
ServiceURL
API (FastAPI)http://localhost:8000
Frontend (Next.js)http://localhost:3001
Redislocalhost:6379
Postgreslocalhost:5433
To confirm everything started cleanly, tail the logs:
make logs
Wait until all services show as healthy before proceeding.
4

Initialize the database

When BACKEND=postgres, the database is initialized automatically from the bundled schema on first start. You don’t need to run any SQL manually.
If you’re using BACKEND=supabase instead, open your Supabase project’s SQL Editor, paste the contents of schemas/schema.sql, and run it before proceeding.
5

Create your account

Open http://localhost:3001 and sign up with an email and password.
6

Connect a GitHub repository

In the Waterline UI, go to Settings → Integrations → GitHub and click Connect GitHub. You’ll be redirected to GitHub to authorize the OAuth app you created.After authorization, select the repository you want to analyze. Waterline will register a webhook on that repo and begin indexing in the background.For a repository with around 500 files, expect indexing to take 3–10 minutes depending on your LLM provider’s throughput. You can watch progress in the UI.
7

Connect your issue tracker

Choose the issue tracker you use:
Go to Settings → Integrations → Jira and click Connect Jira. You’ll be redirected through the Atlassian OAuth flow. Waterline requests read-only access to your Jira projects — no admin permissions are needed.
8

Analyze your first ticket

Once indexing is complete, click Analyze in the sidebar:
  1. Enter a Jira ticket key (e.g. PROJ-42) or a GitHub Issue number
  2. Select the repository to search against
  3. Click Analyze
Waterline returns a progress percentage, a per-criterion breakdown (SATISFIED / PARTIAL / UNSATISFIED), and a list of the most relevant code symbols with their relevance scores.

​
Useful commands

make dev        # Start all services
make stop       # Stop all services
make logs       # Tail API logs
make test       # Run the test suite

​
Next steps