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

```bash
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!):

```bash
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:

```bash
# 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

```bash
pip install codeflash
```

### Step 5: Configure the CLI

```bash
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:
```bash
CODEFLASH_API_KEY=cf-your-api-key-from-step-3
CODEFLASH_AIS_SERVER=local
CODEFLASH_CFAPI_SERVER=local
```

### Step 6: Optimize Your Code!

```bash
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:

```bash
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:

```bash
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

```bash
# 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

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

# Start container
docker start codeflash

# Restart container
docker restart codeflash
```

### Remove Container

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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