Docker Compose Deployment

Deploy Greptile using Docker Compose - the recommended approach

This is the recommended deployment method for most Greptile self-hosting scenarios. Docker Compose provides a simple, flexible, and reliable way to deploy all Greptile services.

Architecture

The Docker Compose deployment includes:

• Greptile API Server: Core application service
• PostgreSQL Database: Primary data storage with pgvector for embeddings
• Redis Cache: Session and temporary data storage
• Nginx Proxy: Reverse proxy and SSL termination
• Supporting Services: Health checks, monitoring, and utilities

Prerequisites

System Requirements

• Operating System: Linux (Ubuntu 20.04+ or CentOS 8+ recommended)
• CPU: Minimum 4 cores, 8+ cores recommended
• Memory: Minimum 8GB RAM, 16GB+ recommended
• Storage: 100GB+ available disk space
• Network: Open ports 80, 443, and any custom ports needed

Software Requirements

• Docker: Version 20.10 or later
• Docker Compose: Version 2.0 or later
• Git: For cloning the repository
• SSL Certificates: Valid certificates for HTTPS

Dependencies

• PostgreSQL Database: AWS RDS or self-hosted
• Redis Cache: AWS ElastiCache or self-hosted
• LLM Provider: OpenAI API, Anthropic, AWS Bedrock, or compatible API

Installation Steps

1. Download the Repository

# Clone the akupara repository
git clone https://github.com/greptileai/akupara.git
cd akupara

# Or download the latest release
wget https://github.com/greptileai/akupara/archive/refs/tags/v0.1.3.tar.gz
tar -xzf v0.1.3.tar.gz
cd akupara-0.1.3

2. Navigate to Docker Directory

cd docker

3. Configure Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit the .env file with your configuration:

# Database Configuration
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DB=greptile
POSTGRES_USER=greptile_user
POSTGRES_PASSWORD=your-secure-password

# Redis Configuration
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

# LLM Configuration
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Application Configuration
GREPTILE_API_HOST=api.yourdomain.com
GREPTILE_WEB_HOST=app.yourdomain.com
SSL_CERT_PATH=/path/to/your/cert.pem
SSL_KEY_PATH=/path/to/your/key.pem

# GitHub Integration
GITHUB_APP_ID=your-github-app-id
GITHUB_APP_PRIVATE_KEY_PATH=/path/to/github-private-key.pem

4. Set Up SSL Certificates

Place your SSL certificates in the appropriate directory:

mkdir -p ssl
cp /path/to/your/certificate.pem ssl/
cp /path/to/your/private-key.pem ssl/

5. Deploy with Docker Compose

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

6. Verify Deployment

Check that all services are running:

# Check application health
curl https://api.yourdomain.com/health

# Check database connectivity
docker-compose exec greptile-api greptile-cli db:status

# View service logs
docker-compose logs greptile-api
docker-compose logs greptile-web

Configuration

Database Setup

Ensure your PostgreSQL database has the pgvector extension:

-- Connect to your PostgreSQL database
CREATE EXTENSION IF NOT EXISTS vector;

LLM Provider Configuration

Configure your preferred LLM provider in the .env file:

OpenAI Configuration

LLM_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4
EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002

Anthropic Configuration

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-api-key
ANTHROPIC_MODEL=claude-3-sonnet-20240229

AWS Bedrock Configuration

LLM_PROVIDER=bedrock
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
BEDROCK_MODEL_ID=anthropic.claude-3-sonnet-20240229-v1:0

GitHub Integration

Set up GitHub App integration:

1. Create a GitHub App in your organization
2. Generate a private key
3. Configure the app settings in your .env file

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_PATH=/app/ssl/github-private-key.pem
GITHUB_WEBHOOK_SECRET=your-webhook-secret

AWS Infrastructure (Optional)

If you want to deploy the supporting infrastructure on AWS, use the Terraform configuration:

cd docker/terraform

# Initialize Terraform
terraform init

# Plan the deployment
terraform plan

# Apply the infrastructure
terraform apply

This will create:

• VPC and networking components
• EC2 instance for Docker Compose
• RDS PostgreSQL database
• ElastiCache Redis cluster
• Application Load Balancer
• Security groups and IAM roles

Maintenance

Updating Greptile

To update to a new version:

# Pull the latest images
docker-compose pull

# Restart services
docker-compose down
docker-compose up -d

# Check update status
docker-compose logs -f

Backup and Recovery

Regular backups are essential:

# Database backup
docker-compose exec postgres pg_dump -U greptile_user greptile > backup.sql

# Redis backup (if using persistence)
docker-compose exec redis redis-cli BGSAVE

# Application data backup
docker-compose exec greptile-api greptile-cli backup:create

Monitoring

Monitor your deployment:

# Service health
docker-compose ps

# Resource usage
docker stats

# Application logs
docker-compose logs -f --tail=100

# Database status
docker-compose exec postgres psql -U greptile_user -d greptile -c "\l"

Troubleshooting

Common Issues

Services won’t start

# Check Docker daemon
sudo systemctl status docker

# Check compose file syntax
docker-compose config

# View detailed logs
docker-compose logs service-name

Database connection errors

# Test database connectivity
docker-compose exec greptile-api nc -zv postgres-host 5432

# Check database logs
docker-compose logs postgres

SSL certificate issues

# Verify certificate files
openssl x509 -in ssl/certificate.pem -text -noout

# Check certificate expiration
openssl x509 -in ssl/certificate.pem -noout -dates

Performance Tuning

Optimize for your environment:

# docker-compose.override.yml
version: '3.8'
services:
  greptile-api:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
    environment:
      - WORKER_PROCESSES=4
      - MAX_CONNECTIONS=1000

  postgres:
    environment:
      - POSTGRES_SHARED_BUFFERS=256MB
      - POSTGRES_EFFECTIVE_CACHE_SIZE=1GB

Support

For deployment issues:

1. Check the akupara repository issues
2. Review the application logs
3. Contact support with your deployment configuration

Keep your .env file secure and never commit sensitive credentials to version control.