bakery-ia/docs/05-deployment/colima-setup.md

# Colima Setup for Local Development

## Overview

Colima is used for local Kubernetes development on macOS. This guide provides the optimal configuration for running the complete Bakery IA stack locally.

## Recommended Configuration

### For Full Stack (All Services + Monitoring)

```bash
colima start --cpu 6 --memory 12 --disk 120 --runtime docker --profile k8s-local
```

### Configuration Breakdown

| Resource | Value | Reason |
|----------|-------|--------|
| **CPU** | 6 cores | Supports 18 microservices + infrastructure + build processes |
| **Memory** | 12 GB | Comfortable headroom for all services with dev resource limits |
| **Disk** | 120 GB | Container images (~30 GB) + PVCs (~40 GB) + logs + build cache |
| **Runtime** | docker | Compatible with Skaffold and Tiltfile |
| **Profile** | k8s-local | Isolated profile for Bakery IA project |

---

## Resource Breakdown

### What Runs in Dev Environment

#### Application Services (18 services)
- Each service: 64Mi-256Mi RAM (dev limits)
- Total: ~3-4 GB RAM

#### Databases (18 PostgreSQL instances)
- Each database: 64Mi-256Mi RAM (dev limits)
- Total: ~3-4 GB RAM

#### Infrastructure
- Redis: 64Mi-256Mi RAM
- RabbitMQ: 128Mi-256Mi RAM
- Gateway: 64Mi-128Mi RAM
- Frontend: 64Mi-128Mi RAM
- Total: ~0.5 GB RAM

#### Monitoring (Optional)
- Prometheus: 512Mi RAM (when enabled)
- Grafana: 128Mi RAM (when enabled)
- Total: ~0.7 GB RAM

#### Kubernetes Overhead
- Control plane: ~1 GB RAM
- DNS, networking: ~0.5 GB RAM

**Total RAM Usage**: ~8-10 GB (with monitoring), ~7-9 GB (without monitoring)
**Total CPU Usage**: ~3-4 cores under load
**Total Disk Usage**: ~70-90 GB

---

## Alternative Configurations

### Minimal Setup (Without Monitoring)

If you have limited resources:

```bash
colima start --cpu 4 --memory 8 --disk 100 --runtime docker --profile k8s-local
```

**Limitations**:
- No monitoring stack (disable in dev overlay)
- Slower build times
- Less headroom for development tools (IDE, browser, etc.)

### Resource-Rich Setup (For Active Development)

If you want the best experience:

```bash
colima start --cpu 8 --memory 16 --disk 150 --runtime docker --profile k8s-local
```

**Benefits**:
- Faster builds
- Smoother IDE performance
- Can run multiple browser tabs
- Better for debugging with multiple tools

---

## Starting and Stopping Colima

### First Time Setup

```bash
# Install Colima (if not already installed)
brew install colima

# Start Colima with recommended config
colima start --cpu 6 --memory 12 --disk 120 --runtime docker --profile k8s-local

# Verify Colima is running
colima status k8s-local

# Verify kubectl is connected
kubectl cluster-info
```

### Daily Workflow

```bash
# Start Colima
colima start k8s-local

# Your development work...

# Stop Colima (frees up system resources)
colima stop k8s-local
```

### Managing Multiple Profiles

```bash
# List all profiles
colima list

# Switch to different profile
colima stop k8s-local
colima start other-profile

# Delete a profile (frees disk space)
colima delete old-profile
```

---

## Troubleshooting

### Colima Won't Start

```bash
# Delete and recreate profile
colima delete k8s-local
colima start --cpu 6 --memory 12 --disk 120 --runtime docker --profile k8s-local
```

### Out of Memory

Symptoms:
- Pods getting OOMKilled
- Services crashing randomly
- Slow response times

Solutions:
1. Stop Colima and increase memory:
   ```bash
   colima stop k8s-local
   colima delete k8s-local
   colima start --cpu 6 --memory 16 --disk 120 --runtime docker --profile k8s-local
   ```

2. Or disable monitoring:
   - Monitoring is already disabled in dev overlay by default
   - If enabled, comment out in `infrastructure/kubernetes/overlays/dev/kustomization.yaml`

### Out of Disk Space

Symptoms:
- Build failures
- Cannot pull images
- PVC provisioning fails

Solutions:
1. Clean up Docker resources:
   ```bash
   docker system prune -a --volumes
   ```

2. Increase disk size (requires recreation):
   ```bash
   colima stop k8s-local
   colima delete k8s-local
   colima start --cpu 6 --memory 12 --disk 150 --runtime docker --profile k8s-local
   ```

### Slow Performance

Tips:
1. Close unnecessary applications
2. Increase CPU cores if available
3. Enable file sharing exclusions for better I/O
4. Use an SSD for Colima storage

---

## Monitoring Resource Usage

### Check Colima Resources

```bash
# Overall status
colima status k8s-local

# Detailed info
colima list
```

### Check Kubernetes Resource Usage

```bash
# Pod resource usage
kubectl top pods -n bakery-ia

# Node resource usage
kubectl top nodes

# Persistent volume usage
kubectl get pvc -n bakery-ia
df -h  # Check disk usage inside Colima VM
```

### macOS Activity Monitor

Monitor these processes:
- `com.docker.hyperkit` or `colima` - should use <50% CPU when idle
- Memory pressure - should be green/yellow, not red

---

## Best Practices

### 1. Use Profiles

Keep Bakery IA isolated:
```bash
colima start --profile k8s-local  # For Bakery IA
colima start --profile other-project  # For other projects
```

### 2. Stop When Not Using

Free up system resources:
```bash
# When done for the day
colima stop k8s-local
```

### 3. Regular Cleanup

Once a week:
```bash
# Clean up Docker resources
docker system prune -a

# Clean up old images
docker image prune -a
```

### 4. Backup Important Data

Before deleting profile:
```bash
# Backup any important data from PVCs
kubectl cp bakery-ia/<pod-name>:/data ./backup

# Then safe to delete
colima delete k8s-local
```

---

## Integration with Tilt

Tilt is configured to work with Colima automatically:

```bash
# Start Colima
colima start k8s-local

# Start Tilt
tilt up

# Tilt will detect Colima's Kubernetes cluster automatically
```

No additional configuration needed!

---

## Integration with Skaffold

Skaffold works seamlessly with Colima:

```bash
# Start Colima
colima start k8s-local

# Deploy with Skaffold
skaffold dev

# Skaffold will use Colima's Docker daemon automatically
```

---

## Comparison with Docker Desktop

### Why Colima?

| Feature | Colima | Docker Desktop |
|---------|--------|----------------|
| **License** | Free & Open Source | Requires license for companies >250 employees |
| **Resource Usage** | Lower overhead | Higher overhead |
| **Startup Time** | Faster | Slower |
| **Customization** | Highly customizable | Limited |
| **Kubernetes** | k3s (lightweight) | Full k8s (heavier) |

### Migration from Docker Desktop

If coming from Docker Desktop:

```bash
# Stop Docker Desktop
# Uninstall Docker Desktop (optional)

# Install Colima
brew install colima

# Start with similar resources to Docker Desktop
colima start --cpu 6 --memory 12 --disk 120 --runtime docker --profile k8s-local

# All docker commands work the same
docker ps
kubectl get pods
```

---

## Summary

### Quick Start (Copy-Paste)

```bash
# Install Colima
brew install colima

# Start with recommended configuration
colima start --cpu 6 --memory 12 --disk 120 --runtime docker --profile k8s-local

# Verify setup
colima status k8s-local
kubectl cluster-info

# Deploy Bakery IA
skaffold dev
# or
tilt up
```

### Minimum Requirements

- macOS 11+ (Big Sur or later)
- 8 GB RAM available (16 GB total recommended)
- 6 CPU cores available (8 cores total recommended)
- 120 GB free disk space (SSD recommended)

### Recommended Machine Specs

For best development experience:
- **MacBook Pro M1/M2/M3** or **Intel i7/i9**
- **16 GB RAM** (32 GB ideal)
- **8 CPU cores** (M1/M2 Pro or better)
- **512 GB SSD**

---

## Support

If you encounter issues:

1. Check [Colima GitHub Issues](https://github.com/abiosoft/colima/issues)
2. Review [Tilt Documentation](https://docs.tilt.dev/)
3. Check Bakery IA Slack channel
4. Contact DevOps team

Happy coding! 🚀