Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt

Use this file to discover all available pages before exploring further.

Caret’s local development environment is fully containerised. A single docker compose up --build command pulls together six services — a React/Vite frontend, an Express API Gateway, three Node.js backend services, and a Python/FastAPI AI service — each built from the same Dockerfiles used in production. No manual service wiring is needed; Docker Compose handles networking, dependency ordering, and health checks automatically so you can focus on writing code rather than managing processes.
Caret does not run a local PostgreSQL instance. Every service that needs a database connects to Supabase Cloud over the public internet via DATABASE_URL. You must provision a Supabase project and populate the required environment variables before starting the stack.

​
Prerequisites

  • Docker Desktop (or Docker Engine + Compose plugin) installed and running.
  • A .env file at the repo root containing the required secrets (see Environment Variables below).

​
Starting the Stack

docker compose up --build
Docker Compose builds each service image, starts them in dependency order, and streams logs to your terminal. Once all health checks pass the stack is ready.
You can also use the Makefile shorthand make up, which runs the same command. Use make up-nocache when you want to force a full rebuild without any layer cache.

​
Services

The table below maps each service to its technology, exposed local port, and health-check command as defined in docker-compose.yml.
ServiceStackLocal PortHealth Check
frontendReact 19 / Vite / Bun5173—
api-gatewayNode.js / Express / TypeScript3000wget -qO- http://localhost:3000/health
auth-serviceNode.js / Express / TypeScript3001wget -qO- http://localhost:3001/health
document-serviceNode.js / Express / Drizzle3002wget -qO- http://localhost:3002/health
collab-serviceNode.js / Y.js / WebSocket3003wget -qO- http://localhost:3003/health
ai-servicePython / FastAPI / PydanticAI8000curl -f http://localhost:8000/health

​
Service health checks

Every backend service is configured with the following health-check parameters in docker-compose.yml: 
healthcheck:
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 10s   # 15 s for ai-service
Wait until all containers report healthy before running integration tests or making API requests. You can monitor health status with: 
docker compose ps

​
Local access URLs

ServiceURL
Frontendhttp://localhost:5173
API Gatewayhttp://localhost:3000
Collab WebSocketws://localhost:3003
AI Servicehttp://localhost:8000
The frontend is pre-wired to call the API Gateway at http://localhost:3000/api/v1 and the collaboration WebSocket at ws://localhost:3003.

​
Environment Variables

Create a .env file at the repo root (next to docker-compose.yml) before starting the stack. Docker Compose reads this file automatically. 
# Supabase — required by auth, document, and collab services
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key  # auth-service and document-service
SUPABASE_JWT_SECRET=your-jwt-secret              # collab-service only

# PostgreSQL connection string (Supabase pooler)
DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

# JWT signing secret shared across Node and AI services
JWT_SECRET=a-long-random-secret

# AI provider keys — at least one is required for AI features
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=deepseek/deepseek-v4-flash  # default model if OPENROUTER_API_KEY is set
Variables not present in .env default to empty strings in the development compose file. Services will start but requests requiring database access or authentication will fail. Always populate at minimum DATABASE_URL, SUPABASE_URL, SUPABASE_ANON_KEY, and JWT_SECRET. The collab service additionally requires SUPABASE_JWT_SECRET; auth and document services require SUPABASE_SERVICE_ROLE_KEY.

​
Viewing Logs

Stream logs for all services at once: 
docker compose logs -f
Stream logs for a single service: 
docker compose logs -f api-gateway
docker compose logs -f ai-service
Or use the Makefile shorthand for all services: 
make logs

​
Stopping the Stack

docker compose down
This stops and removes all containers but preserves built images and volumes. Add -v to also remove named volumes if you need a clean slate. 
docker compose down -v

​
Rebuilding a Single Service

When you change only one service’s code during development, rebuild and restart that service without touching the others: 
docker compose up --build api-gateway
Rebuilding a single service is the fastest inner loop during backend development. For example, after editing the API Gateway route logic, run docker compose up --build api-gateway and your changes will be live in seconds without restarting the frontend or AI service.
Replace api-gateway with any service name from the table above — for example document-service, collab-service, or ai-service.

​
Makefile Reference

The repo Makefile exposes convenience targets that wrap common Docker Compose commands.
TargetCommandDescription
make updocker compose up --buildBuild and start all services
make up-nocachedocker compose build --no-cache && docker compose upFull rebuild, no layer cache
make downdocker compose downStop and remove containers
make logsdocker compose logs -fStream all service logs
make psdocker compose psList container status

Build docs developers (and LLMs) love

Get started for freeTalk to us