bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf0176673cd9caaa97a833d4108284bd0da8878c
bakery-ia/docs/colima-setup.md
Urtzi Alfaro 667e6e0404 New alert service
2025-12-05 20:07:01 +01:00

7.6 KiB
Raw Blame History

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! 🚀