Skip to Content

Quick Start

Local development setup with KIND (Kubernetes in Docker).

Prerequisites

  • Docker 20.10+
  • kubectl
  • Helm 3.x
  • KIND (Kubernetes in Docker)
  • Go 1.23+ (for building services)
  • Python 3.8+ (for isA_common)

Local Cluster Setup

1. Create KIND Cluster

cd deployments/kubernetes/local/scripts
./kind-setup.sh

This creates a KIND cluster with:

  • 1 control plane node
  • 2 worker nodes
  • Ingress support
  • Port mappings for services

2. Build and Load Images

./kind-build-load.sh

Builds Docker images for all gRPC services and loads them into KIND.

3. Deploy Infrastructure

./kind-deploy.sh

Deploys all infrastructure components:

  • PostgreSQL, Redis, Neo4j
  • NATS, MQTT (Mosquitto)
  • MinIO, Qdrant, DuckDB
  • Loki, Grafana
  • Consul, APISIX

4. Verify Services

./check-services.sh

Manual Setup

Create Cluster

kind create cluster --name isa-cloud --config kind-config.yaml

Deploy with Helm

# Add Helm repos
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add hashicorp https://helm.releases.hashicorp.com
helm repo add apisix https://charts.apiseven.com
 
# Deploy infrastructure
helm install postgresql bitnami/postgresql -n isa-cloud-staging
helm install redis bitnami/redis -n isa-cloud-staging
helm install consul hashicorp/consul -n isa-cloud-staging
helm install apisix apisix/apisix -n isa-cloud-staging

Port Forwarding

Access services locally:

# All services
./scripts/port-forward.sh
 
# Infrastructure only
./scripts/port-forward-infra.sh

Service Ports

ServiceLocal Port
APISIX Gateway9080
APISIX Admin9180
Consul UI8500
Consul DNS8600
PostgreSQL5432
Redis6379
Neo4j HTTP7474
Neo4j Bolt7687
NATS4222
MQTT1883
MinIO API9000
MinIO Console9001
Qdrant6333
Grafana3000
Loki3100

Build Commands

# Build all services
make build
 
# Build specific service
make build-postgres
make build-redis
 
# Run tests
make test
 
# Lint code
make lint
 
# Generate protobuf
make proto

Configuration

Development Config

# configs/examples/development.yaml
postgres:
  host: localhost
  port: 5432
  database: isa_dev
 
redis:
  host: localhost
  port: 6379
 
consul:
  host: localhost
  port: 8500

Environment Variables

export ISA_ENV=development
export ISA_LOG_LEVEL=debug
export POSTGRES_HOST=localhost
export REDIS_HOST=localhost
export CONSUL_HTTP_ADDR=localhost:8500

Verify Installation

Check Pods

kubectl get pods -n isa-cloud-staging

Check Services in Consul

curl http://localhost:8500/v1/catalog/services | jq

Test gRPC Service

grpcurl -plaintext localhost:50061 list

Troubleshooting

Pods Not Starting

kubectl describe pod <pod-name> -n isa-cloud-staging
kubectl logs <pod-name> -n isa-cloud-staging

Service Not Registered

Check Consul health:

curl http://localhost:8500/v1/health/service/<service-name>

Connection Refused

Verify port forwarding:

kubectl port-forward svc/postgres 5432:5432 -n isa-cloud-staging

Next Steps

Home