Skip to main content

Local Orchestration Setup

This guide details the dual-orchestration environment used in the monorepo. Local development uses two specialized container pipelines:

  • Podman Compose via Podman Desktop: Used for high-velocity local coding, database testing, and general developer workflows using daemonless containers.
  • Kubernetes via Minikube & Skaffold: Used to validate configurations, routing, service discovery, and production-like environment policies with automated hot-reloading.

Tooling Prerequisites​

To run and manage the local orchestration environment, install the appropriate tools on your machine.

1. Podman Container Engine & Podman Desktop​

For high-velocity local microservice coding and database testing:

  • Podman Desktop: GUI and management suite for daemonless Podman machines running over WSL2 on Windows.
  • Podman CLI & Podman Compose: CLI tools for container and pod management.
  • Install command (PowerShell): 
    winget install RedHat.Podman-Desktop RedHat.Podman

Required Podman Desktop Extensions​

Inside Podman Desktop (Settings -> Extensions), ensure the following extensions are installed and enabled:

  1. Podman Extension: Core extension for managing Podman machines, images, containers, and volumes.
  2. Compose Extension: Required to parse and execute podman compose workflows for multi-container development.
  3. Kubectl CLI Extension: Integrates kubectl cluster controls and Kubernetes context switching directly inside Podman Desktop.
No Shell Aliases Policy

Our project scripts explicitly invoke podman compose and podman exec directly in package.json. Do not create shell aliases (such as alias docker=podman). Using explicit podman commands ensures reproducible execution across all developer workstations and CI pipelines.

2. Kubernetes Environment (Minikube via VirtualBox or Podman)​

For local Kubernetes testing, routing validation, and deployment pipelines. Our workflow leverages two complementary strategies:

  • Approach A (Automated Local Dev): Uses host-installed minikube, kubectl, and skaffold with the virtualbox or podman driver for live hot-reloading and instant full-stack cluster deployment.
  • Approach B (Production Staging Simulation): Runs 100% inside an isolated VirtualBox Ubuntu VM simulating cloud production hosts without requiring Kubernetes tooling on the Windows host.

Install the following tools on your Windows host:

  • Oracle VirtualBox: The hypervisor hosting our Kubernetes nodes.
  • kubectl: Minikube bundles its own version of kubectl (accessible via minikube kubectl --). However, installing the native client is highly recommended for automatic integration with tools like OpenLens and Skaffold.
  • Skaffold: Required on host for Approach A. Automates build and deploy pipelines. If using Approach B, Skaffold runs entirely inside the VM and is not needed on the host.
  • OpenLens: Visual cluster monitoring client.
  • Install command (PowerShell): 
    # Omit Kubernetes.kubectl or Google.Skaffold if using Approach B exclusively
    winget install Oracle.VirtualBox Kubernetes.kubectl Google.Skaffold Lens.OpenLens

Depending on your goals, choose one or both of the following VM deployment approaches:

  • Approach A: Local VM Development (Minikube ISO) Minikube automatically provisions and manages its own optimized VM inside VirtualBox.

    • Extra Host Tool: Requires Minikube CLI on the Windows host.
    • Install command (PowerShell): 
      winget install Kubernetes.minikube

  • Approach B: Production Staging Simulation (Ubuntu Server LTS VM) A manually provisioned Ubuntu Server LTS VM in VirtualBox where Minikube runs inside the VM (simulating actual cloud production hosts).

Avoid Running Skaffold via Containers

Although you can run Skaffold inside a container, doing so requires mounting container sockets and remapping internal hosts. Furthermore, live file synchronization (pnpm k8s:dev) often fails to propagate file system events across container boundaries. For this reason, installing the native Skaffold binary locally is strongly recommended.

1. Podman Compose Container Engine Setup​

For fast feedback loops, we run microservices and backing databases using Podman Compose.

Podman Machine Configuration​

  1. Initialize and start the default Podman machine: 
    podman machine init
    podman machine start
  2. Verify Podman engine status: 
    podman info

Workspace Script Execution​

Instead of running verbose Podman Compose commands manually, use the predefined Turborepo filters and scripts in the root package.json:

  • Start Platform Services: pnpm platform:up
  • Stop Platform Services: pnpm platform:down
  • Reset Platform State: pnpm platform:reset (deletes volumes)
  • Start Cortex Stack: pnpm cortex:core:up or pnpm cortex:mcp:up
  • Stop Cortex Stack: pnpm cortex:core:down or pnpm cortex:mcp:down

2. Minikube Local Cluster Setup​

When you need to test network policies, cross-namespace DNS resolution, or Traefik ingress configurations, you must deploy the workspaces to Minikube.

Approach A: Local VM Development (VirtualBox Driver)​

Minikube automatically creates and boots a lightweight Linux VM (minikube-iso) in VirtualBox.

Creating the Cluster​

Create a dedicated Minikube profile named tupynambalucas using the virtualbox driver:

minikube start -p tupynambalucas --driver=virtualbox --kubernetes-version=v1.30.0

Manual ISO Acquisition & Cache Configuration (Optional/Offline)​

If your environment has restricted internet access, or if you prefer to manually manage the Minikube ISO, you can acquire and configure it as follows:

  1. Acquire the ISO: Download the official Minikube ISO matching your target Kubernetes version from the Google Cloud Storage bucket or GitHub Releases:

  2. Configure the ISO Location: You can point Minikube to your downloaded ISO using one of the following methods:

    • Option 1: CLI Flag (One-time run) Pass the path using the file:// scheme to the --iso-url flag:

      minikube start -p tupynambalucas --driver=virtualbox --kubernetes-version=v1.30.0 --iso-url=file://C:/path/to/minikube-v1.30.0.iso

    • Option 2: Persistent Minikube Config (Recommended) Configure the ISO path globally so it is automatically used for every start:

      minikube config set iso-url file://C:/path/to/minikube-v1.30.0.iso

    • Option 3: Direct Local Cache Injection (No config changes) Place the downloaded .iso file directly in Minikube's default cache subdirectory. Minikube checks this location before attempting to download:

      • Windows Path: %USERPROFILE%\.minikube\cache\iso\minikube-v1.30.0.iso
      • Unix Path: ~/.minikube/cache/iso/minikube-v1.30.0.iso

3. Visualizing the Cluster with OpenLens​

To monitor resource consumption, inspect logs, and manage namespaces visually, we use OpenLens on the Windows host.

Connecting to Approach A (Local VM)​

OpenLens automatically reads standard kubeconfig configurations located at ~/.kube/config.

  1. Set the active context to the Minikube profile in your terminal: 
    kubectl config use-context tupynambalucas
  2. Open OpenLens or Podman Desktop.
  3. Select the cluster context named tupynambalucas.

4. Professional Orchestration with Skaffold​

Instead of manually building each container image and applying Kubernetes manifests one by one, we use Skaffold to orchestrate the entire development process.

Skaffold handles:

  • Concurrent Builds: Building all required service images in parallel.
  • Dynamic Tagging: Automatically updating image tags inside your Kubernetes manifests to match the current build signature.
  • Continuous Development: Watching files and syncing code changes to active Pod containers in real time without triggering full container rebuilds.

Launching the Cluster and Workspaces​

We provide simplified scripts in the root package.json to manage the lifecycle:

  1. Deploy and Run in the Background: To build all images and deploy all platform and cortex components to Minikube:

    pnpm k8s:up

  2. Continuous Development Mode (Live Hot-Reloading): To run Skaffold in development mode, watching source code changes and automatically hot-reloading code inside the running pods:

    pnpm k8s:dev

  3. Stop and Clean Up: To tear down all resources, namespaces, and workloads deployed by Skaffold:

    pnpm k8s:down