Local Development Docker Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Local Development Docker Setup provides a containerized environment to run the AI Code Reviewer project. It ensures consistency across development environments by encapsulating the PostgreSQL database, the Next.js web application, and the background worker process. This setup allows developers to simulate a production-like environment locally while managing dependencies and service interconnections through Docker Compose.
Sources: docker-compose.yml:1-12, README.md:188-193
System Architecture
The local Docker environment consists of three primary services sharing a single PostgreSQL database. The architecture separates concerns between synchronous HTTP handling and asynchronous background processing.
Component Overview
| Service | Image/Target | Role |
|---|---|---|
| Postgres | pgvector/pgvector:pg16 | Relational database with vector support for AI embeddings. |
| Web | Dockerfile target: web | Next.js server handling UI, OAuth, and webhooks. |
| Worker | Dockerfile target: worker | Node.js process for LLM calls and GitHub API interactions. |
Sources: docker-compose.yml:18-68, README.md:83-93
Service Interaction Flow
The following diagram illustrates how the local services interact during a typical workflow, such as receiving a webhook.
The Web service acts as the entry point for external webhooks, while the Worker service handles the heavy lifting by polling jobs from the PostgreSQL database via pg-boss.
Sources: README.md:9-37, docker-compose.yml:20-68
Service Configuration
PostgreSQL (postgres)
The system uses pgvector to support future RAG (Retrieval-Augmented Generation) features. It is configured to persist data in a named volume to ensure database state is maintained across container restarts.
- Image:
pgvector/pgvector:pg16 - Port:
5432 - Healthcheck: Uses
pg_isreadyto ensure the database is available before the application services start.
Sources: docker-compose.yml:20-37, package.json:20-21
Web Application (web)
The Next.js application runs in the web container. It is responsible for serving the user interface and handling the initial intake of GitHub webhooks.
- Environment: Connects to the database via
DATABASE_URL. - Dependencies: Depends on the
postgresservice being healthy. - Port:
3000
Sources: docker-compose.yml:39-51, apps/web/package.json:7-14
Background Worker (worker)
The worker container runs the background tasks defined in the apps/worker directory. It shares the same codebase and Docker image as the web service but uses a different entry point (target).
- Service Name: Explicitly set to
workervia environment variables. - Initialization: Configured with
SKIP_DB_INIT: '1'because migrations are handled by the web container startup. - Scaling: Designed to scale independently based on the ingestion backlog.
Sources: docker-compose.yml:53-68, apps/worker/README.md:14-17
Environment Variables
The local setup requires a .env or .env.local file to populate secrets and configurations.
| Variable | Source | Description |
|---|---|---|
DATABASE_URL | Compose File | Internal Docker connection string for PostgreSQL. |
GITHUB_APP_ID | .env | Numeric ID from GitHub App settings. |
OPENAI_API_KEY | .env | API key for processing AI reviews. |
ENCRYPTION_KEY | .env | 64 hex chars for encrypting stored secrets. |
SKIP_DB_INIT | Compose File | Prevents worker from running redundant migrations. |
Sources: docker-compose.yml:45-66, README.md:200-213, turbo.json:6-26
Execution Commands
Development and Docker management are facilitated through npm scripts defined in the root package.json.
# Start the full stack (Web + Worker + Postgres)
npm run docker:run
# Start only the database for native local development
npm run docker:up
# Shut down the Docker services
npm run docker:down
# Wipe database volumes during shutdown
docker compose down -v
Sources: package.json:16-22, docker-compose.yml:1-12
Summary
The Local Development Docker Setup provides a robust, multi-container environment that mirrors the production architecture. By splitting the web and worker processes and utilizing a shared PostgreSQL instance with pg-boss, the system ensures that long-running LLM reviews do not block the high-availability requirements of GitHub webhook responses.
Sources: README.md:83-100, apps/worker/README.md:14-17