codeflash-internal/deployment/onprem-simple/README.md

Codeflash On-Premise Deployment

A single Docker container that runs all Codeflash services for on-premise deployments.

What's Inside

The unified container includes:

• PostgreSQL 15 - Database server (port 5432)
• aiservice - Python Django optimization service (port 8000)
• cf-api - Node.js API server (port 3001)
• cf-webapp - Next.js web interface (port 3000)
• Supervisord - Process manager for all services

Quick Start

Prerequisites

• Docker installed (version 20.10 or higher)
• An AI provider API key (Azure OpenAI, OpenAI, or Anthropic)

Step 1: Build the Docker Image

git clone https://github.com/codeflash-ai/codeflash
cd codeflash
docker build -f deployment/onprem-simple/Dockerfile.unifiedall -t codeflash/unified:latest .

Build time: ~5-10 minutes

Step 2: Run the Container

The simplest way to run Codeflash (only 1 required environment variable!):

docker run -d --name codeflash \
  -e AZURE_OPENAI_API_KEY=your-azure-api-key \
  -p 5432:5432 \
  -p 8000:8000 \
  -p 3001:3001 \
  -p 3000:3000 \
  -v codeflash-data:/var/lib/postgresql/data \
  codeflash/unified:latest

What happens automatically:

• ✅ DATABASE_URL defaults to built-in PostgreSQL
• ✅ SECRET_KEY auto-generated
• ✅ URLs default to localhost
• ✅ API key auto-generated on first run

Step 3: Get Your API Key

After the container starts (~15 seconds), retrieve your API key:

# View logs to see the API key
docker logs codeflash

# Or get it from the saved file
docker exec codeflash cat /app/API_KEY.txt

You'll see output like:

======================================
  CODEFLASH SETUP COMPLETE!
======================================

Your API Key: cf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Save this API key! You'll need it to configure the Codeflash CLI.
======================================

Save this API key - you'll need it for the CLI!

Step 4: Install the CLI

pip install codeflash

Step 5: Configure the CLI

export CODEFLASH_API_KEY=cf-your-api-key-from-step-3
export CODEFLASH_AIS_SERVER=local
export CODEFLASH_CFAPI_SERVER=local

Or create a .env file in your project:

CODEFLASH_API_KEY=cf-your-api-key-from-step-3
CODEFLASH_AIS_SERVER=local
CODEFLASH_CFAPI_SERVER=local

Step 6: Optimize Your Code!

cd your-python-project
codeflash --file path/to/file.py --function function_name --no-pr

Configuration Options

Minimal Configuration (Recommended)

Only provide your AI provider key:

docker run -d --name codeflash \
  -e OPENAI_API_TYPE=azure \
  -e OPENAI_API_BASE=your-azure-openai-base-url \
  -e AZURE_OPENAI_API_KEY=your-key \
  -p 5432:5432 -p 8000:8000 -p 3001:3001 -p 3000:3000 \
  -v codeflash-data:/var/lib/postgresql/data \
  codeflash/unified:latest

Full Configuration (Optional)

You can customize all settings if needed:

docker run -d --name codeflash \
  -e OPENAI_API_TYPE=azure \
  -e OPENAI_API_BASE=your-azure-openai-base-url \
  -e AZURE_OPENAI_API_KEY=your-azure-key \
  -e ANTHROPIC_API_KEY=your-anthropic-key \
  -e SECRET_KEY=your-custom-secret \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e NEXT_PUBLIC_APP_URL=http://your-domain:3000 \
  -e WEBAPP_URL=http://your-domain:3000 \
  -e CODEFLASH_CFAPI_URL=http://your-domain:3001 \
  -p 5432:5432 -p 8000:8000 -p 3001:3001 -p 3000:3000 \
  -v codeflash-data:/var/lib/postgresql/data \
  codeflash/unified:latest

See .env.onprem.minimal for all available options.

Container Management

Check Status

# Check if container is running
docker ps | grep codeflash

# View logs
docker logs codeflash

# Follow logs in real-time
docker logs -f codeflash

# Check service status inside container
docker exec codeflash supervisorctl status

Expected output:

postgres                         RUNNING   pid 40, uptime 0:10:23
aiservice                        RUNNING   pid 41, uptime 0:10:23
cf-api                           RUNNING   pid 42, uptime 0:10:23
cf-webapp                        RUNNING   pid 43, uptime 0:10:23

Stop/Start/Restart

# Stop container (data persists in volume)
docker stop codeflash

# Start container
docker start codeflash

# Restart container
docker restart codeflash

Remove Container

# Remove container (keeps data volume)
docker stop codeflash
docker rm codeflash

# Remove container AND data (⚠️ deletes all data!)
docker stop codeflash
docker rm codeflash
docker volume rm codeflash-data

Upgrade to New Version

# Pull or build new image
docker pull codeflash/unified:latest
# OR
docker build -f deployment/onprem-simple/Dockerfile.unifiedall -t codeflash/unified:latest .

# Stop and remove old container
docker stop codeflash
docker rm codeflash

# Start new container (data persists in volume)
docker run -d --name codeflash \
  -e AZURE_OPENAI_API_KEY=your-key \
  -p 5432:5432 -p 8000:8000 -p 3001:3001 -p 3000:3000 \
  -v codeflash-data:/var/lib/postgresql/data \
  codeflash/unified:latest

Accessing Services

Once running, you can access:

• cf-api: http://localhost:3001
• aiservice: http://localhost:8000
• cf-webapp: http://localhost:3000
• PostgreSQL: localhost:5432 (username: codeflash, password: codeflash, database: codeflash)

Troubleshooting

Container won't start

# Check logs for errors
docker logs codeflash

# Verify ports are available
lsof -i :5432
lsof -i :8000
lsof -i :3001
lsof -i :3000

Services not responding

# Check service status
docker exec codeflash supervisorctl status

# Restart a specific service
docker exec codeflash supervisorctl restart cf-api
docker exec codeflash supervisorctl restart aiservice
docker exec codeflash supervisorctl restart cf-webapp

CLI can't connect

# Test service endpoints
curl http://localhost:3001/cfapi/healthcheck
curl http://localhost:8000/health

# Verify environment variables
echo $CODEFLASH_API_KEY
echo $CODEFLASH_AIS_SERVER
echo $CODEFLASH_CFAPI_SERVER

Database issues

# Check if PostgreSQL is ready
docker exec codeflash pg_isready -h localhost -p 5432 -U codeflash

# Access database
docker exec -it codeflash psql postgresql://codeflash:codeflash@localhost:5432/codeflash

# Check API keys in database
docker exec codeflash psql postgresql://codeflash:codeflash@localhost:5432/codeflash \
  -c "SELECT key, suffix FROM cf_api_keys;"

FAQ

Q: Do I need GitHub App configuration? A: No, not if you use --no-pr mode. GitHub integration is optional.

Q: Do I need Stripe configuration? A: No, billing features are not required for on-premise deployments.

Q: What AI providers are supported? A: Azure OpenAI, OpenAI, and Anthropic Claude. You only need one.

Q: Can I use my own PostgreSQL database? A: Yes, set the DATABASE_URL environment variable.

Q: What ports need to be accessible? A: For CLI usage, only ports 3001 (cf-api) and 8000 (aiservice) are required. Port 3000 (webapp) is for the web interface, and 5432 (PostgreSQL) is only if you want direct database access.

Q: How much disk space is needed? A: ~5GB for the image, plus storage for your data (depends on usage).

Q: How much memory is needed? A: Minimum 2GB RAM, recommended 4GB+ for optimal performance.

Performance Notes

• Container size: ~5GB (includes all services and dependencies)
• Startup time: ~15-20 seconds for all services
• Memory usage: ~500MB-2GB (depending on workload)
• CPU: Works on both x86_64 and ARM64 (Apple Silicon)

File Structure

deployment/onprem-simple/
├── Dockerfile.unifiedall        # Main unified Docker image
├── supervisord.conf             # Process manager configuration
├── startup.sh                   # Container startup script
├── init-db.sh                   # Database initialization script
├── .env.onprem.minimal          # Minimal environment variables template
├── .dockerignore                # Docker build exclusions
├── README.md                    # This file
├── TESTING.md                   # Testing guide
└── archive/                     # Old/experimental files
    ├── old-dockerfiles/         # Previous Dockerfile attempts
    ├── old-compose/             # Old docker-compose files
    └── old-scripts/             # Previous build scripts

Next Steps

• ✅ Container built and running
• ✅ Database initialized
• ✅ API key generated
• ✅ CLI configured
• 🚀 Ready to optimize code!

See TESTING.md for a complete testing guide with example workflows.

Support

For issues or questions:

• GitHub Issues: https://github.com/codeflash-ai/codeflash/issues
• Documentation: https://docs.codeflash.ai