Local Development Deployment
Deploy Optimal Platform on your local machine using Kind (Kubernetes in Docker) for development and testing.
Prerequisites
Ensure you have the following installed:
| Tool | Version | Purpose |
|---|---|---|
| Docker | 24.0+ | Container runtime |
| Kind | 0.20+ | Local Kubernetes clusters |
| kubectl | 1.28+ | Kubernetes CLI |
| Helm | 3.13+ | Package manager |
# Verify all prerequisites
make doctor
Quick Setup
1. Clone Repository
git clone https://github.com/optimal-cyber/optimal-platform.git
cd optimal-platform
2. Create Local Cluster
# Create Kind cluster with ingress support
kind create cluster --name optimal-local --config k8s/local/kind-config.yaml
# Verify cluster is running
kubectl cluster-info --context kind-optimal-local
The Kind config includes:
- Ingress-ready node labels
- Port mappings for HTTP (80) and HTTPS (443)
- Extra mounts for persistent data
3. Install Dependencies
# Add Helm repositories
make helm-deps
# This adds:
# - bitnami (PostgreSQL, Redis)
# - grafana (Loki, Promtail)
# - jetstack (cert-manager)
# - ingress-nginx
4. Deploy Platform
# Deploy with local development values
make deploy-local
# Or manually with Helm
helm upgrade --install optimal-platform k8s/helm-charts/optimal-platform \
--namespace optimal-system \
--create-namespace \
-f k8s/helm-charts/optimal-platform/values-development.yaml
5. Wait for Pods
# Watch pods come up
kubectl get pods -n optimal-system -w
# Check all pods are ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=optimal-platform \
-n optimal-system --timeout=300s
Access Services
Port Forwarding
# Start port forwarding for all services
make port-forward
# Or forward individual services
kubectl port-forward svc/optimal-portal 3000:80 -n optimal-system
kubectl port-forward svc/optimal-api-gateway 8000:8000 -n optimal-system
kubectl port-forward svc/grafana 3001:80 -n optimal-system
kubectl port-forward svc/keycloak 8080:80 -n optimal-system
Service URLs
| Service | URL | Default Credentials |
|---|---|---|
| Portal | http://localhost:3000 | SSO via Keycloak |
| API Gateway | http://localhost:8000/docs | - |
| Grafana | http://localhost:3001 | admin / prom-operator |
| Keycloak | http://localhost:8080 | admin / (see values.yaml) |
| Harbor | http://localhost:8082 | admin / Harbor12345 |
Development Workflow
Hot Reloading
For portal development:
# Start portal in dev mode
cd apps/portal
npm install
npm run dev
For API gateway:
# Start API with hot reload
cd apps/api-gateway
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
View Logs
# All pods
kubectl logs -n optimal-system -l app.kubernetes.io/instance=optimal-platform --tail=100
# Specific service
kubectl logs -n optimal-system -l app=optimal-portal -f
# API Gateway
kubectl logs -n optimal-system -l app=optimal-api-gateway -f
Database Access
# PostgreSQL
kubectl port-forward svc/optimal-platform-postgresql 5432:5432 -n optimal-system
# Connect with psql
PGPASSWORD=$(kubectl get secret optimal-platform-postgresql -n optimal-system \
-o jsonpath='{.data.password}' | base64 -d) \
psql -h localhost -U optimal_user -d optimal_platform
Cleanup
# Delete the deployment
helm uninstall optimal-platform -n optimal-system
# Delete the Kind cluster
kind delete cluster --name optimal-local
Troubleshooting
Pods stuck in Pending
kubectl describe pod <pod-name> -n optimal-system
Common causes:
- Insufficient resources (increase Docker memory to 8GB+)
- PVC pending (check storage class)
Cannot access services
# Check ingress controller
kubectl get pods -n ingress-nginx
# Check service endpoints
kubectl get endpoints -n optimal-system
Database connection errors
# Check PostgreSQL pod
kubectl logs -n optimal-system -l app.kubernetes.io/name=postgresql
# Verify credentials
kubectl get secret optimal-platform-postgresql -n optimal-system -o yaml