mni Development Environment

Complete development environment setup for mni backend controllers and frontend UI apps.

Quick Start

Run the complete setup:

./setup-all.sh

This will:

1. Install all required tools (including GitHub CLI and Node.js)
2. Download mnibuilder from private repo (prompts for GitHub login if needed)
3. Clone/update backend and frontend repositories
4. Configure environment
5. Start Docker registry
6. Prepare Go and npm dependencies
7. Optionally start the full development environment

Required Tools

All tools are installed as binaries (no package manager dependencies):

• Go 1.24.2 - Programming language
• Node.js 22.x / npm - Frontend development runtime
• Docker - Container runtime
• mnibuilder - mNi Cloud project scaffolding tool
• aqua - CLI version manager
• direnv - Environment variable management (installed but not required)
• tmux - Terminal multiplexer for managing Tilt sessions
• yq - YAML processor
• Tilt - Kubernetes development tool
• gh - GitHub CLI for authentication and repository access

Components

Configured in components.yaml:

• dependency-controller - Provides CRDs, must start first
• auth-controller - Auth API and CRDs
• api-gateway - API gateway service
• vpc-controller - VPC management controller
• vm-controller, ctr-controller, bs-controller, vpn-controller - Service controllers
• cli - Command line interface (no Tiltfile)
• nginx frontend routing - Routes frontend UI apps at http://localhost:8000 using nginx.conf
• API gateway port-forward - Exposes the gateway at http://localhost:8080

Add new components by editing components.yaml.

Individual Scripts

setup-tools.sh

Installs all required development tools as binaries.

./setup-tools.sh

clone-repos.sh

Clones or updates backend and frontend repositories from GitHub using GitHub CLI.

./clone-repos.sh

Automatically uses gh auth login if not authenticated.

setup-env.sh

Configures environment variables and installs aqua packages.

./setup-env.sh

setup-registry.sh

Starts Docker registry at localhost:5000.

./setup-registry.sh

prepare-deps.sh

Downloads Go dependencies, runs initial backend builds, and installs frontend npm dependencies.

./prepare-deps.sh

tilt-up.sh

Starts backend Tilt instances, frontend Vite apps, and nginx routing in a tmux session.

./tilt-up.sh

• Creates tmux session "mni-tilt"
• Starts dependency-controller first
• Each backend component gets its own tmux window
• Starts each frontend app in its own tmux window by default
• Starts nginx from nginx.conf in a Docker container
• Starts the API gateway port-forward in an api-gateway-pf tmux window
• Backend Tilt UIs use the ports configured in components.yaml
• Frontend UI is available at http://localhost:8000

tilt-down.sh

Stops all tmux-managed backend Tilt and frontend processes, stops nginx, then optionally cleans up Kubernetes resources.

./tilt-down.sh

tilt-status.sh

Shows status of tmux windows, Tilt instances, frontend apps, nginx, Docker registry, and Kubernetes deployments.

./tilt-status.sh

Environment Variables

Automatically configured:

• GOPRIVATE=github.com/mNi-Cloud
• TILT_ALLOW_K8S_CONTEXT=kubernetes-admin@kubernetes
• TILT_REGISTRY=localhost:5000
• VITE_API_BASE_URL=http://localhost:8080
• VITE_API_NAMESPACE=default

Development URLs

After running tilt-up.sh:

• dependency-controller: http://localhost:10350
• auth-controller: http://localhost:10351
• api-gateway: http://localhost:10352
• vpc-controller: http://localhost:10353
• vm-controller: http://localhost:10354
• ctr-controller: http://localhost:10355
• bs-controller: http://localhost:10356
• vpn-controller: http://localhost:10357
• API gateway: http://localhost:8080
• frontend UI: http://localhost:8000

Tmux Commands

• Attach to session: tmux attach -t mni-tilt
• List windows: Ctrl-b w
• Switch window: Ctrl-b [number]
• Detach: Ctrl-b d

Troubleshooting

GitHub Access

The setup uses GitHub CLI for authentication. If not already authenticated:

# Login to GitHub (will be prompted during clone-repos.sh)
gh auth login

# Manual login if needed
gh auth login --web

# Check authentication status
gh auth status

GitHub CLI automatically handles authentication for git operations.

Docker Registry

If registry is not accessible:

docker run -d --restart=unless-stopped --name registry -p 5000:5000 registry:2

Kubernetes Connection

Ensure kubectl is configured:

kubectl cluster-info

Adding New Components

1. Edit components.yaml:

- name: new-controller
  repo: https://github.com/mNi-Cloud/new-controller.git
  type: controller
  has_tiltfile: true
  tilt_port: 10353
  required: false

2. Run setup:

./clone-repos.sh
./setup-env.sh
./prepare-deps.sh
./tilt-up.sh

Components with has_tiltfile: true will be automatically managed by Tilt.