Self-Hosting Guide#

Deploy WatchLLM on your own infrastructure for complete control over data, performance, and compliance.

Overview#

WatchLLM's self-hosted option gives enterprises full ownership of the caching proxy, dashboard, and data layer. All components run on your infrastructure — no data ever leaves your network.

Architecture#

A self-hosted WatchLLM deployment consists of three core components:

Prerequisites#

• Docker v20+ and Docker Compose v2+
• Node.js v18+ and pnpm v8+
• A Supabase project (self-hosted or cloud)
• An Upstash Redis instance (or self-hosted Redis)
• A Cloudflare account (for Workers deployment)
• Domain name with DNS access

Quick Start with Docker#

1. Clone the Repository#

git clone https://github.com/kaadipranav/WATCHLLM.git
cd WATCHLLM

2. Configure Environment Variables#

cp self-hosted/.env.example .env

Edit .env with your credentials:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
 
# Redis
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=AX...
 
# Auth
NEXTAUTH_SECRET=your-random-secret
NEXTAUTH_URL=https://your-domain.com
 
# Stripe (optional)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

3. Run Database Migrations#

npx supabase db push

4. Deploy the Dashboard#

cd dashboard
pnpm install
pnpm build
pnpm start

5. Deploy the Worker#

cd worker
pnpm install
npx wrangler deploy

Manual Deployment#

Dashboard (Next.js)#

Deploy the dashboard to any platform that supports Next.js:

Worker (Cloudflare Workers)#

cd worker
cp wrangler.toml.example wrangler.toml
# Edit wrangler.toml with your account details
npx wrangler deploy

Database Schema#

Apply the schema migrations in order:

cd supabase/migrations
# Apply each migration file in order
psql $DATABASE_URL -f 001_initial.sql
psql $DATABASE_URL -f 002_usage_logs.sql
# ... continue for all migration files

Security Considerations#

• Rotate secrets regularly — especially SUPABASE_SERVICE_ROLE_KEY
• Enable RLS — Row Level Security is configured in the migrations
• Use HTTPS — Always deploy behind TLS
• Restrict CORS — Configure allowed origins in worker settings
• Audit logs — Monitor usage_logs for unusual patterns

Scaling#

Horizontal Scaling#

• Dashboard: Deploy multiple instances behind a load balancer
• Worker: Cloudflare Workers scale automatically across 300+ edge locations
• Redis: Use Upstash serverless Redis for auto-scaling

Vertical Scaling#

• Database: Upgrade your Supabase plan for more connections and storage
• Workers: Increase CPU time limits in wrangler.toml

Monitoring#

Set up monitoring with these recommended tools:

• Sentry — Error tracking (already integrated in the dashboard)
• Grafana + Prometheus — Metrics and dashboards
• Upstash Console — Redis usage monitoring
• Supabase Dashboard — Database performance

Updating#

To update your self-hosted instance:

git pull origin main
cd dashboard && pnpm install && pnpm build
cd ../worker && pnpm install && npx wrangler deploy

Always check the Changelog for breaking changes before updating.

Support#

• GitHub Issues: github.com/kaadipranav/WATCHLLM/issues
• Email: kiwi092020@gmail.com
• Discord: Join our community for real-time support