Local Development Setup¶

Complete guide for setting up a local development environment for the RCIIS DevOps platform.

Prerequisites¶

Refer to the Prerequisites section for detailed installation instructions.

Required Tools¶

Docker and Kind for local Kubernetes clusters
kubectl for cluster management
Helm for package management
SOPS and Age for secret management
Git for version control
VS Code or preferred IDE

Local Cluster Setup¶

Cilium-based Cluster (Recommended)¶

# Create local cluster with Cilium CNI
./scripts/create_local_cilium.sh

# Verify cluster status
kubectl get nodes
kubectl get pods -A

Calico-based Cluster (Alternative)¶

# Create local cluster with Calico CNI
./scripts/create_local.sh

# Verify cluster status
kubectl get nodes
kubectl get pods -A

Infrastructure Deployment¶

Core Infrastructure¶

# Deploy core infrastructure components
kubectl apply -f apps/infra/

# Wait for infrastructure to be ready
kubectl wait --for=condition=ready pod -l app=cert-manager -n cert-manager --timeout=300s
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx --timeout=300s

ArgoCD Installation¶

# Install ArgoCD
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  --values apps/infra/argocd/staging/values.yaml

# Get ArgoCD admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

Application Development¶

Secret Management¶

# Generate Age key for local development
age-keygen -o ~/.age/local.key

# Export Age key for SOPS
export SOPS_AGE_KEY_FILE=~/.age/local.key

# Decrypt secrets for local use
sops --decrypt apps/rciis/secrets/local/nucleus/appsettings.yaml > /tmp/appsettings.yaml

Local Development Workflow¶

Code Changes

# Make code changes
git checkout -b feature/my-feature

# Build and test locally
docker build -t nucleus:local .
kind load docker-image nucleus:local

Deploy to Local Cluster

# Update image tag in values
yq '.image.tag = "local"' -i apps/rciis/nucleus/local/values.yaml

# Deploy application
helm upgrade --install nucleus charts/rciis \
  --namespace nucleus \
  --create-namespace \
  --values apps/rciis/nucleus/local/values.yaml

Test Changes

# Port forward for local access
kubectl port-forward -n nucleus svc/nucleus-service 8080:80

# Test API endpoints
curl http://localhost:8080/api/health

Database Development¶

Local SQL Server¶

# Deploy SQL Server for development
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install mssql bitnami/mssql \
  --namespace database \
  --create-namespace \
  --set auth.rootPassword=DevPassword123!

# Connect to database
kubectl exec -it -n database mssql-0 -- /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P DevPassword123!

Database Migrations¶

# Run Entity Framework migrations
dotnet ef database update --project src/Nucleus.Data

# Create new migration
dotnet ef migrations add <MigrationName> --project src/Nucleus.Data

Message Queue Development¶

Local Kafka Setup¶

# Deploy Strimzi operator
kubectl apply -f apps/rciis/strimzi/local/

# Wait for Kafka cluster to be ready
kubectl wait --for=condition=Ready kafka/kafka-cluster -n kafka --timeout=300s

# Create development topics
kubectl apply -f apps/rciis/strimzi/local/extra/kafka-topic.yaml

Testing Message Flow¶

# Producer test
kubectl exec kafka-cluster-kafka-0 -n kafka -- \
  bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 \
  --topic customs-declarations

# Consumer test
kubectl exec kafka-cluster-kafka-0 -n kafka -- \
  bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic customs-declarations \
  --from-beginning

File Storage Development¶

Local MinIO Setup¶

# Deploy MinIO
kubectl apply -f apps/rciis/minio/local/

# Access MinIO console
kubectl port-forward -n minio svc/minio-console 9001:9001
# Open http://localhost:9001

MinIO Testing¶

# Install MinIO client
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc

# Configure MinIO client
mc alias set local http://localhost:9000 minioadmin minioadmin

# Create bucket and upload test file
mc mb local/test-bucket
echo "test content" | mc pipe local/test-bucket/test.txt

API Gateway Development¶

Local APISIX Setup¶

# Deploy APISIX
kubectl apply -f apps/rciis/apisix/local/

# Access APISIX dashboard
kubectl port-forward -n apisix svc/apisix-dashboard 9000:9000
# Open http://localhost:9000

Route Testing¶

# Test direct service access
curl http://localhost:9080/api/health

# Test through APISIX gateway
curl -H "Host: api.local" http://localhost:9080/api/health

Debugging and Troubleshooting¶

Common Issues¶

Pod Not Starting

# Check pod status
kubectl describe pod <pod-name> -n <namespace>

# Check logs
kubectl logs <pod-name> -n <namespace>

# Check events
kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp

Service Connection Issues

# Check service endpoints
kubectl get endpoints <service-name> -n <namespace>

# Test service connectivity
kubectl run debug --image=busybox -it --rm -- /bin/sh
# Inside pod: nslookup <service-name>.<namespace>

Secret Decryption Issues

# Verify Age key
echo $SOPS_AGE_KEY_FILE

# Test decryption
sops --decrypt apps/rciis/secrets/local/nucleus/appsettings.yaml

Performance Monitoring¶

# Monitor resource usage
kubectl top nodes
kubectl top pods -A

# Check cluster events
kubectl get events --sort-by=.metadata.creationTimestamp -A

# Monitor specific namespace
watch kubectl get pods -n nucleus

IDE Configuration¶

VS Code Setup¶

Required Extensions
Kubernetes
Docker
YAML
GitLens
C# (for .NET development)

Workspace Settings

{
  "kubernetes.namespace": "nucleus",
  "yaml.schemas": {
    "https://raw.githubusercontent.com/instrumenta/kubernetes-json-schema/master/v1.18.0-standalone-strict/all.json": "*.yaml"
  }
}

Debugging Configuration¶

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Nucleus API",
      "type": "coreclr",
      "request": "launch",
      "program": "${workspaceFolder}/src/Nucleus.API/bin/Debug/net8.0/Nucleus.API.dll",
      "args": [],
      "cwd": "${workspaceFolder}/src/Nucleus.API",
      "stopAtEntry": false,
      "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  ]
}

Testing Strategy¶

Unit Testing¶

# Run unit tests
dotnet test src/Nucleus.Tests/

# Run with coverage
dotnet test src/Nucleus.Tests/ --collect:"XPlat Code Coverage"

Integration Testing¶

# Start test environment
docker-compose -f docker-compose.test.yml up -d

# Run integration tests
dotnet test src/Nucleus.IntegrationTests/

# Cleanup test environment
docker-compose -f docker-compose.test.yml down

End-to-End Testing¶

# Deploy test applications
helm test nucleus -n nucleus

# Run API tests
kubectl apply -f tests/e2e/api-tests.yaml

# Check test results
kubectl logs -n nucleus job/api-tests

Cleanup¶

Remove Applications¶

# Remove all applications
helm uninstall nucleus -n nucleus
helm uninstall kafka -n kafka
helm uninstall minio -n minio

# Remove namespaces
kubectl delete namespace nucleus kafka minio

Remove Cluster¶

# Delete Kind cluster
./scripts/delete_local.sh

# Verify cleanup
docker ps | grep kind
kubectl config get-contexts

Best Practices¶

Development Workflow¶

Feature branches: Use git flow for feature development
Small commits: Atomic changes with clear messages
Regular testing: Test changes in local environment
Documentation: Update docs with code changes

Resource Management¶

Resource limits: Set appropriate limits for local pods
Namespace isolation: Use separate namespaces for different components
Secret management: Use local secrets for development
Regular cleanup: Remove unused resources periodically

Security Considerations¶

Local secrets: Use development-only credentials
Network isolation: Limit external access in local environment
Image scanning: Scan custom images for vulnerabilities
Access control: Use minimal required permissions

For production deployment, refer to the Operations documentation.