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)

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:

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:

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

# 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

# Start Colima
colima start k8s-local

# Your development work...

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

Managing Multiple Profiles

# 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

# 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:

   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:

   docker system prune -a --volumes
   

2. Increase disk size (requires recreation):

   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

# Overall status
colima status k8s-local

# Detailed info
colima list

Check Kubernetes Resource Usage

# 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:

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:

# When done for the day
colima stop k8s-local

3. Regular Cleanup

Once a week:

# Clean up Docker resources
docker system prune -a

# Clean up old images
docker image prune -a

4. Backup Important Data

Before deleting profile:

# 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:

# 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:

# 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:

# 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)

# 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
2. Review Tilt Documentation
3. Check Bakery IA Slack channel
4. Contact DevOps team

Happy coding! 🚀