Skip to main content

Tilt

Tilt is the normal development entrypoint for Lumie. This page is a how-to guide for starting the shared dev stack where the frontend runs locally and the backend, workers, and stateful services run in the dev cluster.

Prerequisites​

  • A workspace checkout with .github/tilt-up.sh
  • A working SSH host alias named k3s, because the script opens the tunnel with ssh ... k3s
  • A kubeconfig at $HOME/.kube/lumie-k3s.yaml, which the script exports as KUBECONFIG
  • ssh, nc, lsof, and tilt installed locally, because the script calls each of them directly
  • lumie-frontend dependencies installed locally, because the frontend Tiltfile starts npm run dev

Step 1: Start Tilt From The Workspace Root​

cd /path/to/Lumie
.github/tilt-up.sh

Expected success signals:

  • the script prints Starting SSH tunnel to k3s API (localhost:6443)...
  • the script prints Tunnel ready
  • Tilt starts and shows a lumie-frontend resource linked to http://localhost:3000

What The Workspace Script Does​

The script does three things before handing off to tilt up:

  1. Opens an SSH tunnel so the K3s API is reachable at localhost:6443.
  2. Exports KUBECONFIG=$HOME/.kube/lumie-k3s.yaml.
  3. Runs tilt up from .github/, forwarding any extra arguments.

When the session ends, the script closes the SSH control socket and cleans up stale tunnel state on the next run if needed.

Runtime Split​

Frontend​

lumie-frontend/Tiltfile defines a local_resource that runs:

npm run dev

The frontend stays on your machine and serves http://localhost:3000. Current local env values such as NEXT_PUBLIC_API_BASE are injected directly by the Tiltfile, so the standard Tilt path does not depend on a checked-in .env.example or a hand-written .env.local.

Backend and workers​

The backend and worker Tiltfiles build and deploy workloads into the lumie-dev namespace. Those services run against the shared cluster-side PostgreSQL, RabbitMQ, Redis, and MinIO instances instead of local copies.

Workers use live-update style container sync for a tighter inner loop, while the backend follows the cluster deployment path expected by the Java application.

Step 2: Open The Local Frontend​

Open http://localhost:3000 after Tilt reports the lumie-frontend resource as running.

Expected success signal: the browser reaches the local Next.js app instead of a cluster hostname, and frontend edits hot-reload without redeploying the cluster.

How Browser Requests Reach The Backend​

The browser does not call the cluster API origin directly during the normal local flow. Instead:

  1. The browser talks to the local frontend on http://localhost:3000.
  2. Frontend API calls go through same-origin /api/... routes.
  3. app/api/[...path]/route.ts proxies those requests to NEXT_PUBLIC_API_BASE.
  4. The proxy strips Domain and Secure from Set-Cookie headers so auth cookies land correctly on localhost.

This keeps login and browser session behavior predictable in local development even though the backend itself is running in the cluster.

Verification​

nc -z 127.0.0.1 6443

Expected success signal: the command exits successfully while Tilt is running, confirming the SSH tunnel is up.

curl -I http://localhost:3000

Expected success signal: you get an HTTP response from the local frontend instead of connection refused.

Common Failures​

  • ERROR: Tunnel not ready after 15s usually means the k3s SSH alias is missing, the cluster is unreachable, or port 6443 is blocked.
  • tilt: command not found means Tilt is not installed on the laptop.
  • The lumie-frontend resource fails immediately if npm run dev cannot start, usually because dependencies are missing in lumie-frontend.
  • Login cookies break if you bypass the frontend proxy and browse https://dev.lumie-infra.com/ directly; that host serves API routes, and the bare root returns 404.
  • Do not move next dev into the cluster. The frontend Tiltfile and workspace rules intentionally keep HMR local.

Where To Go Next​