Luma turns a handful of servers into a deployment platform you can operate from your laptop, CI, or browser. Describe a service in YAML, choose where it runs and how it is reached, then deploy through one authenticated API.
Underneath, Nomad schedules containers, Traefik routes traffic, and Cloudflare manages DNS. Luma connects those pieces with application history, secrets, builds, node management, and a web console. Deployment clients carry a management token; infrastructure credentials stay with the control plane.
# status.yaml
name: status
image: traefik/whoami:v1.10.3
region: cn
exposure: cn-edge
domain: status.example.com
port: 80
luma validate status.yaml
luma deploy status.yaml --dry-run
luma deploy status.yaml
The example assumes an initialized manager and a domain in your Cloudflare zone. Set up your first manager below.
Why Luma
- One workflow across your machines. Place services in
cn, global, home, or custom regions. Pin a workload to a named node when placement matters.
- Separate placement from networking. Run a service at home and expose it through a public relay, or run a cloud worker with no public ingress.
- Start from an image or a repository. Deploy existing images, build on your machine, or import a GitHub/Gitea repository through a configured Builder.
- Operate from the console. Inspect applications, logs, routes, builds, registry images, and node health. Manage upgrades with visible progress and route checks.
- Keep delivery reproducible. Validate manifests, preview a deployment, inspect job history, and roll back a Nomad job version. CI uses the same API as the CLI.
- Keep configuration scoped. Application secrets and private registry credentials are managed centrally; manifests reference values without embedding them.
Luma fits personal infrastructure and small teams running web apps, APIs, and workers on a few machines. The control plane currently uses one Manager with local SQLite storage. Multi-active Manager high availability and Kubernetes-style tenant isolation are outside that model. See storage and recovery before relying on it for production.
Quick start
1. Install the CLI
On the manager and any machine you want to deploy from:
curl -fsSL https://raw.githubusercontent.com/LiuTianjie/luma/main/scripts/install-luma.sh | sh
~/.local/bin/luma doctor --local
The installer creates an isolated Python environment and places luma in ~/.local/bin. Open a new shell if that directory is not yet on your PATH. Installing the CLI does not bootstrap a server.
Python 3.9+ is required. Use a virtual environment on systems with externally managed Python:
python -m venv .venv
. .venv/bin/activate
python -m pip install "luma-infra==0.2.64"
See installation lifecycle for runtime diagnostics and uninstall behavior.
2. Bootstrap one manager
Have these ready:
| Requirement | Purpose |
|---|
| A Linux server; Ubuntu 22.04+ is the documented starting point | Runs Luma Control, Nomad, and Traefik; start with 2 CPU cores / 8 GiB RAM, including Control's 4 GiB reservation |
| A domain managed in Cloudflare | Control API and application domains |
| A Cloudflare API token with Zone Read and DNS Edit | DNS record management |
| Public ports 80/443 and an ACME email address | HTTP ingress and HTTPS certificates |
| Access to the configured container registry | Pulls the Control image and application images |
Run on the manager:
luma bootstrap --domain luma.example.com
The CLI prompts for missing values, provisions the runtime, initializes SQLite, and prints the dashboard URL, management token, and node join token. Keep both tokens private.
If the manager needs a proxy to pull the default GHCR image, configure EGRESS_SUBSCRIPTION_URL before bootstrap. This is especially relevant on mainland China hosts. Tailscale and a Builder Registry are not prerequisites for the first single-manager workload. See getting started for network and host setup.
3. Run the first workload
Open https://luma.example.com/dashboard/, use the management token for the first sign-in, then add a passkey in Settings → Sign-in for future access (sign-in and recovery). Choose Applications → Create application → hello-world first install.
This deploys the repository's hello-world template with exposure: none. It verifies scheduling without adding an application domain. For a public service, use status.yaml above with a domain you own.
From a laptop or CI machine, authenticate and deploy through Control:
luma login https://luma.example.com --token-stdin < token.txt
luma deploy status.yaml
luma status
luma app versions status
luma init scaffolds a manifest like status.yaml, including a memory limit and health check. Image deployment clients need the CLI and access to Control. Local source builds additionally need Docker/Buildx.
How it works
flowchart LR
Clients[CLI / CI / Dashboard] -->|Authenticated API| Control[Luma Control]
Control -->|Job specifications| Nomad[Nomad]
Nomad --> Cloud[Cloud nodes]
Nomad --> Home[Home nodes]
Control -->|DNS records| DNS[Cloudflare]
Visitors[Application traffic] --> Edge[Traefik ingress]
Edge --> Cloud
Edge -->|Configured relay| Home
The deployment path and the application traffic path are separate. Control submits jobs; application requests go through the configured ingress. Each workload runs on a Nomad client using the Docker driver.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
