Skip to main content

Docker Compose Deployment

This guide covers deploying Caracal Core using Docker Compose with PostgreSQL, Gateway Proxy, and MCP Adapter services.

Prerequisites​

  • Docker 20.10+ and Docker Compose 1.29+
  • At least 4GB RAM available for containers
  • TLS certificates for gateway proxy

Quick Start​

1. Clone and Navigate​

git clone https://github.com/Garudex-Labs/Caracal.git
cd Caracal

2. Create Environment File​

cp .env.example .env

Edit .env and set your configuration:

# Change the database password in production
DB_PASSWORD=your_secure_password_here

# Configure authentication mode (mtls, jwt, or api_key)
AUTH_MODE=jwt

# Optional: Configure MCP servers
MCP_SERVERS=local:http://localhost:3000

3. Certificate Setup​

Create a certs directory with TLS certificates:

mkdir -p certs

Development (Self-Signed):

# Generate CA certificate
openssl req -x509 -newkey rsa:4096 -keyout certs/ca.key -out certs/ca.crt \
  -days 365 -nodes -subj "/CN=Caracal CA"

# Generate server certificate
openssl req -newkey rsa:4096 -keyout certs/server.key -out certs/server.csr \
  -nodes -subj "/CN=localhost"

openssl x509 -req -in certs/server.csr -CA certs/ca.crt -CAkey certs/ca.key \
  -CAcreateserial -out certs/server.crt -days 365

# Generate JWT key pair
openssl genrsa -out certs/jwt_private.pem 4096
openssl rsa -in certs/jwt_private.pem -pubout -out certs/jwt_public.pem

rm certs/server.csr

Production: Copy your production certificates to the certs directory.

4. Start Services​

docker-compose up -d
docker-compose logs -f

5. Initialize Database​

docker-compose exec postgres pg_isready -U caracal
docker-compose exec gateway caracal db init

6. Verify Services​

docker-compose ps
curl -k https://localhost:8443/health
curl http://localhost:8080/health

Service Endpoints​

ServiceURLDescription
Gateway HTTPShttps://localhost:8443Main API gateway
Gateway Healthhttps://localhost:8443/healthHealth check
MCP Adapterhttp://localhost:8080MCP protocol adapter
Prometheushttp://localhost:9090/metricsMetrics endpoint
PostgreSQLlocalhost:5432Database

Common Commands​

Service Management​

docker-compose up -d          # Start services
docker-compose stop           # Stop services
docker-compose down           # Remove containers
docker-compose down -v        # Remove containers and volumes
docker-compose restart        # Restart all services

Logs and Debugging​

docker-compose logs -f                    # All logs
docker-compose logs -f gateway            # Gateway logs
docker-compose logs --tail=100 gateway    # Last 100 lines

CLI Commands​

docker-compose exec gateway caracal agent list
docker-compose exec gateway caracal policy list
docker-compose exec gateway caracal ledger summary

Database Operations​

# Access database
docker-compose exec postgres psql -U caracal -d caracal

# Backup
docker-compose exec postgres pg_dump -U caracal caracal > backup.sql

# Restore
docker-compose exec -T postgres psql -U caracal caracal < backup.sql

Troubleshooting​

Services Won't Start​

  1. Check Docker versions: docker --version && docker-compose --version
  2. Check logs: docker-compose logs
  3. Verify config: docker-compose config

Database Connection Errors​

  1. Verify PostgreSQL is running: docker-compose ps postgres
  2. Check health: docker-compose exec postgres pg_isready -U caracal
  3. Review credentials in .env

TLS Certificate Errors​

  1. Verify certificates exist: ls -la certs/
  2. Check validity: openssl x509 -in certs/server.crt -text -noout

Production Checklist​

  • Change default database password
  • Use production TLS certificates
  • Configure firewall rules
  • Enable mTLS authentication
  • Set up log aggregation
  • Configure backup strategy
  • Review resource limits
  • Set up alerting

Next Steps​