Getting Started
Local Demo
Spin up a full demo environment on your machine.
Spin up the entire flex.plane control plane locally — identity provider, mesh network, Kubernetes, orchestrator, and portal. One command, all Docker. Perfect for evaluation, development, or just poking around.
This sets up a demo environment for evaluation and development. It is not intended for production use.
Prerequisites
| Tool | Install |
|---|---|
| Docker Desktop | Required for all services |
| Homebrew | kubectl is auto-installed if missing |
One command
make quickstart
That's it. The first run takes 2–3 minutes.
What you get
Once the quickstart completes, you have a fully functional flex.plane control plane:
| Service | URL |
|---|---|
| Portal | http://localhost:3000/portal/ |
| GraphQL Playground | http://localhost:8080/playground |
| Zitadel Console | http://id.localhost:8085/ui/console |
Login with admin / Flexplane1!
No compute nodes are connected yet — the quickstart only starts the control plane. To actually manage VMs, you need to add a Proxmox node.
What happens under the hood
- Preflight checks — verifies Docker is running and required ports are available.
- Docker Compose — starts PostgreSQL, Zitadel (identity provider), Headscale (mesh network), and k3s (lightweight Kubernetes).
- Bootstrap — creates the Zitadel organization, project, service accounts, OIDC applications, and custom claims. Extracts kubeconfig from k3s. Generates API keys for Headscale.
- Application services — starts the orchestrator, portal, and nginx gateway.
Managing the demo
# Stop all services (preserves data)
make quickstart-stop
# Start again (skips bootstrap if already done)
make quickstart
# Destroy everything (removes all data)
make quickstart-destroy
Troubleshooting
Ports already in use
The quickstart needs ports 3000, 6443, 8080, 8085, 9090, and 50443. If any are occupied, you will see an error during preflight. Free the port or stop the conflicting service.
Starting over
make quickstart-destroy
make quickstart