Quickstart

Deploy a sample HTTP service on a local Bex cluster. This developer quickstart runs the operator from source against Kubernetes nodes hosted in Docker. It does not install the full dashboard, API, or public domain routing.

If you already have access to a Bex dashboard, start with Hosted setup when you still need an account or workspace, or Web services when the workspace is ready.

Before you begin​

Install Git, Docker (OrbStack also works), the Go version declared in lego/go.work (currently Go 1.27), make, kubectl, kind, clusterctl, and Helm. Start Docker before running the bootstrap script. The first run downloads Kubernetes and Cluster API components and can take several minutes.

The current mock-cluster.sh uses macOS-style sed -i '' when rewriting its kubeconfig. These commands follow that macOS local setup. Linux users should review that script's in-place editing command before running it.

1. Clone the repository and create the cluster​

In your first terminal:

git clone https://github.com/bex-co/bex.git
cd bex
bash scripts/mock-cluster.sh
export KUBECONFIG="$PWD/infra/local/bex.kubeconfig"
kubectl get nodes

The script creates a management cluster and a separate app cluster, then writes infra/local/bex.kubeconfig for the app cluster. Check that its nodes become Ready before continuing.

2. Install the resource definitions and run the operator​

In the same terminal:

cd lego/operator
make install
BEX_RUNTIME=kubernetes make run

Leave this process running. It watches Bex resources and reconciles them into Kubernetes workloads. This source-based workflow does not require building and loading an operator container into every local node.

3. Deploy the sample application​

Open a second terminal and change to the cloned repository:

cd /path/to/bex
export KUBECONFIG="$PWD/infra/local/bex.kubeconfig"
kubectl apply -f examples/whoami-app.yaml
kubectl get apps.app.bex.co -w

The sample runs traefik/whoami with two replicas. It sets both spec.port and WHOAMI_PORT_NUMBER to 8080, because this image reads its own port variable rather than the platform's injected PORT.

Wait for the App to report Running, then press Ctrl-C to stop watching. This stops the watch command, not the application or operator.

4. Open the application​

kubectl port-forward service/whoami 8080:8080

Leave the command running and open http://localhost:8080 in your browser. The response includes the request details and the container's hostname. If port 8080 is already in use, forward 8081:8080 and open port 8081 instead.

An address ending in .svc belongs to Kubernetes service discovery. It is not a public browser URL; port forwarding provides the local connection.

5. Try scaling​

From another terminal with the app-cluster kubeconfig set, run these commands from the repository root:

bash scripts/mock-cluster.sh scale 2
kubectl patch apps.app.bex.co whoami --type merge -p '{"spec":{"replicas":6}}'
kubectl get pods -l app.bex.co/app=whoami -o wide

The script raises the tenant worker pool's minimum size to two machines. The App patch requests six replicas. Machine provisioning and pod placement are asynchronous; inspect the node column as new pods become ready.

If the application does not become ready​

kubectl describe apps.app.bex.co whoami
kubectl get pods -l app.bex.co/app=whoami -o wide
kubectl get events --sort-by=.lastTimestamp

• Resource type not found: run make install against the app-cluster kubeconfig, then apply the sample again.
• App remains pending: check that make run is still running and that both terminals use infra/local/bex.kubeconfig.
• Pods remain pending: inspect pod events for scheduling or image-pull errors and verify that tenant nodes are ready.
• Connection refused: wait for a ready pod and confirm the sample still sets WHOAMI_PORT_NUMBER and spec.port to the same port.

Clean up the sample​

kubectl delete -f examples/whoami-app.yaml

Stop the port-forward and operator processes with Ctrl-C. Deleting the sample leaves the local clusters available for your next experiment.

Next steps​

• App resources and Blueprints explains the two configuration formats.
• Docker deploys covers your own container images.
• The infrastructure runbook covers a full platform installation and Hetzner infrastructure.
• Platform recovery rehearses isolated restores of platform state after you operate a real installation.