3c3d3ce042
Frontend Changes: - Fix runtime error: Remove undefined handleModify reference from ActionQueueCard in DashboardPage - Migrate PurchaseOrderDetailsModal to use correct PurchaseOrderItem type from purchase_orders service - Fix item display: Parse unit_price as string (Decimal) instead of number - Use correct field names: item_notes instead of notes - Remove deprecated PurchaseOrder types from suppliers.ts to prevent type conflicts - Update CreatePurchaseOrderModal to use unified types - Clean up API exports: Remove old PO hooks re-exported from suppliers - Add comprehensive translations for PO modal (en, es, eu) Documentation Reorganization: - Move WhatsApp implementation docs to docs/03-features/notifications/whatsapp/ - Move forecast validation docs to docs/03-features/forecasting/ - Move specification docs to docs/03-features/specifications/ - Move deployment docs (Colima, K8s, VPS sizing) to docs/05-deployment/ - Archive completed implementation summaries to docs/archive/implementation-summaries/ - Delete obsolete FRONTEND_CHANGES_NEEDED.md - Standardize filenames to lowercase with hyphens 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
388 lines
7.6 KiB
Markdown
388 lines
7.6 KiB
Markdown
# 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! 🚀
|