Skip to main content

Docker Setup Guide for Rippler

This guide explains how to build and run the Rippler platform using Docker.

Prerequisites​

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Git with submodules initialized
  • At least 8GB RAM available for Docker

Quick Start​

  1. Initialize submodules (if not already done):

    make init
    # or
    git submodule update --init --recursive

  2. Create environment file:

    cp .env.example .env
    # Edit .env with your API keys

  3. Build and run all services:

    make build
    make up

  4. Check service status:

    make ps
    make health

Service Architecture​

Infrastructure​

  • PostgreSQL (port 5432): Main database
  • Redis (port 6379): Cache and message broker

Backend Services​

  • API Gateway (port 8000): Main API entry point
  • Embedding Server (port 8001): Text embedding service
  • LLM Service (port 8002): Language model integration
  • Impact Analyzer (port 8003): Code impact analysis
  • Notification Service (port 8004): Notification handling
  • Webhook Handler (port 8005): GitHub webhook processor
  • Dependency Graph Engine (port 8006): Dependency analysis
  • Launchpad (port 8007): Repository onboarding service

Frontend​

  • Rippler UI (port 3000): Next.js web interface

Development Mode​

Run services with hot reload:

make up-dev

This will:

  • Mount source code as volumes
  • Enable auto-reload for code changes
  • Set debug logging levels
  • Enable development tools

Run Specific Services​

# Run only backend services
make dev-services

# Run backend in Docker, UI locally
make dev-ui-local

# Run only infrastructure + API gateway
make dev-api-gateway

# Run impact analyzer with dependencies
make dev-analyzer

# Run dependency graph with dependencies
make dev-graph

# Run launchpad with dependencies
make dev-launchpad

Building Services​

Build all services​

make build

Build specific service​

docker-compose build <service-name>
# Examples:
docker-compose build api-gateway
docker-compose build rippler-ui

Build UI only​

make build-ui

Managing Services​

Start services​

make up              # Start in background
make up-verbose      # Start with logs
make up-dev          # Start in development mode

Stop services​

make down            # Stop services
make down-clean      # Stop and remove volumes

View logs​

make logs            # All services
make logs-api-gateway    # Specific service
make logs-rippler-ui     # UI service

Restart services​

make restart         # Restart all
make restart-api-gateway  # Restart specific service

Dockerfile Details​

Python Services (FastAPI)​

  • Base: python:3.11-slim
  • Multi-stage: No (single stage for faster development)
  • Hot reload: Enabled in dev mode with --reload flag
  • Health checks: HTTP endpoints on /health

Services using this pattern:

  • api-gateway
  • embedding-server
  • impact-analyzer
  • llm-service
  • notification-service
  • webhook-handler

Java Services (Spring Boot)​

  • Base: eclipse-temurin:17-jdk-alpine (build), eclipse-temurin:17-jre-alpine (runtime)
  • Multi-stage: Yes (for smaller image size)
  • Maven: Uses wrapper (mvnw)
  • Health checks: Spring Actuator on /actuator/health

Services using this pattern:

  • launchpad
  • dependency-graph-engine

Next.js UI​

  • Base: node:20-alpine
  • Multi-stage: Yes (deps, builder, runner)
  • Production optimized with standalone output
  • Health checks: Custom Node.js health endpoint

Environment Variables​

Required variables (set in .env):

# LLM Service
OPENAI_API_KEY=<your-key>
ANTHROPIC_API_KEY=<your-key>
LLM_PROVIDER=openai

# GitHub
GITHUB_TOKEN=<your-token>
GITHUB_WEBHOOK_SECRET=<your-secret>

# Notifications
SENDGRID_API_KEY=<your-key>
NOTIFICATION_EMAIL=your-email@example.com

Troubleshooting​

Services won't start​

# Check logs
make logs

# Check if ports are already in use
netstat -tulpn | grep -E '(8000|8001|8002|8003|8004|8005|8006|8007|3000|5432|6379)'

# Clean everything and restart
make clean
make build
make up

Database connection issues​

# Check PostgreSQL is healthy
docker-compose ps postgres

# Check database logs
docker-compose logs postgres

# Reset database
make down-clean
make up

Submodule issues​

# Re-sync submodules
make submodule-sync

# Update all submodules
make pull

# Check submodule status
make submodule-status

Build cache issues​

# Rebuild without cache
docker-compose build --no-cache

# Remove all images and rebuild
docker-compose down --rmi all
make build

Health Checks​

Check all services:

make health

Or manually:

curl http://localhost:8000/health    # API Gateway
curl http://localhost:8001/health    # Embedding Server
curl http://localhost:8002/health    # LLM Service
curl http://localhost:8003/health    # Impact Analyzer
curl http://localhost:8004/health    # Notification Service
curl http://localhost:8005/health    # Webhook Handler
curl http://localhost:8006/actuator/health  # Dependency Graph
curl http://localhost:8007/actuator/health  # Launchpad
curl http://localhost:3000           # UI

Testing​

# Run all tests
make test

# Run UI tests
make test-ui

# Run integration tests
make test-integration

Cleanup​

# Stop and remove containers
make down

# Stop and remove volumes (data loss!)
make down-clean

# Full cleanup (removes images, cache, etc.)
make clean

Production Deployment​

For production:

  1. Use production compose file:

    make prod-build
    make prod-up

  2. Set production environment variables

  3. Configure proper secrets management

  4. Set up SSL/TLS certificates

  5. Configure backup strategies for PostgreSQL

  6. Set up monitoring and logging

Service URLs​

make urls

Output:

📍 Service URLs:
  Rippler UI:           http://localhost:3000
  API Gateway:          http://localhost:8000
  Embedding Server:     http://localhost:8001
  LLM Service:          http://localhost:8002
  Impact Analyzer:      http://localhost:8003
  Notification Service: http://localhost:8004
  Webhook Handler:      http://localhost:8005
  Dependency Graph:     http://localhost:8006
  Launchpad:            http://localhost:8007
  PostgreSQL:           localhost:5432
  Redis:                localhost:6379

Tips​

  • Use make help to see all available commands
  • Services are connected via a Docker network (rippler-network)
  • Volume mounts in dev mode enable hot reload
  • Health checks ensure services start in correct order
  • All services use consistent logging formats

Support​

For issues:

  1. Check logs: make logs
  2. Check health: make health
  3. Review service-specific README files
  4. Open an issue on GitHub