Skip to content

Local Dev Setup

Before You Read

This guide is for running services locally on your laptop for development. For deploying to the dev cluster see GitOps Workflow.

Prerequisites

  • Docker Desktop installed and running
  • GCP authentication configured (gcloud auth application-default login)
  • Repositories cloned (see Onboarding)

Option 1: Connect to Dev Cluster Services

The simplest approach for local development is to run your application locally but connect to the real dev cluster's databases and messaging infrastructure.

Port-Forward Dev Cluster Services

# Port-forward Cloud SQL proxy (requires Cloud SQL Auth Proxy)
# Install: https://cloud.google.com/sql/docs/mysql/connect-auth-proxy
cloud_sql_proxy -instances=orofi-dev-cloud:us-central1:orofi-dev-cloud-dev-oro-mysql-instance=tcp:3306 &

# Port-forward Redis
kubectl port-forward -n redis svc/redis 6379:6379 &
# Or use Cloud Memorystore directly if your IP is in the trusted range:
# redis.dev.orofi.xyz:6379

# Port-forward Kafka
kubectl port-forward -n kafka svc/kafka 9092:9092 &

# Port-forward MongoDB
kubectl port-forward -n mongo-db svc/mongo-db 27017:27017 &

Dev cluster access

Your IP must be in the trusted ranges (35.226.57.140/32, 10.0.0.0/8) to reach the dev cluster directly. If you're working from a different network, use a VPN or bastion host. [NEEDS TEAM INPUT: describe VPN/bastion setup if applicable.]

Configure Local Environment

[NEEDS TEAM INPUT: describe how a developer configures their local .env or application config to point at port-forwarded services. Include any required environment variables.]

Option 2: Docker Compose (Local Mocks)

[NEEDS TEAM INPUT: does a docker-compose.yml exist for local development? If yes, describe its location and how to use it. If not, note that this is a gap.]

If a Docker Compose setup exists, it should start: - A local MySQL instance with the same schema as production - A local Redis instance - A local Kafka instance (single-broker KRaft) - Any mock services needed

# If docker-compose.yml exists at repository root:
docker compose up -d

# Check all services are healthy
docker compose ps

# View logs
docker compose logs -f microservice-identity

Option 3: Minikube / Kind (Full Local Cluster)

[NEEDS TEAM INPUT: does the team have a Minikube or Kind setup for local full-cluster testing? Document if yes.]

Getting Secrets Locally

For local development, you'll need secrets that match what services expect. There are two approaches:

Approach A: Fetch from GCP Secret Manager

# Fetch a secret value (requires secretmanager.secretAccessor permission)
gcloud secrets versions access latest \
  --secret=dev-microservice-identity-secret \
  --project=orofi-dev-cloud

# Or use the GCP console:
# https://console.cloud.google.com/security/secret-manager?project=orofi-dev-cloud

Approach B: Use Dev Cluster Secrets

# Get secret from the running dev cluster
kubectl get secret microservice-identity-secret \
  -n microservice-identity \
  -o jsonpath='{.data}' | base64 -d

Never commit secrets

Do not commit secret values to Git, even in .env.local files. Add .env.local and .env to your .gitignore.

Local Testing Against Dev Services

If your service is running locally but connected to dev cluster services:

  1. Start required port-forwards
  2. Configure your application to use localhost:{port} instead of the cluster DNS names
  3. [NEEDS TEAM INPUT: any special configuration needed for Kafka consumer group IDs to avoid conflicting with dev cluster consumers?]

See Also