Quickstart
This guide installs the daemon on a Linux server, connects the CLI, deploys an app with a Postgres database and an HTTPS domain, then removes it again.
1. Prepare the server
You need:
- Ubuntu 22.04 or later or Debian, with root access over SSH.
- Docker 24 or newer installed and running. The installer checks for Docker and does not install it.
- Caddy 2.8 or later. On Ubuntu and Debian the installer installs it when missing or older than 2.8.0.
- Ports 22, 80 and 443 open. Caddy listens on 80 and 443 and uses port 80 for certificate challenges.
- A DNS A record, for example
hello.example.com, pointing at the server's public address. - Outbound HTTPS from the server for the release download, image pulls and certificate issuance.
Install Docker on Ubuntu or Debian
On a fresh host, choose one method below. We recommend the distro package when it provides Docker Engine 24 or later because apt manages its updates with the rest of the OS. Start by installing the download tools:
$ sudo apt-get update
$ sudo apt-get install -y ca-certificates curlFor the Ubuntu or Debian distro package:
$ sudo apt-get install -y docker.ioAlternatively, Docker's official convenience script detects Ubuntu or Debian and installs Docker from its own repository. Use this path for a test server. Download and read it first:
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ less get-docker.sh
$ sudo sh ./get-docker.shDocker recommends the convenience script for testing and development only. For a production host whose distro package is older than 24, use Docker's official apt repository instructions forUbuntu orDebian. Do not mix distro and Docker repository packages.
After either method, start Docker and check that the Server version is 24 or later:
$ sudo systemctl enable --now docker
$ sudo docker versionThe docker group is root-equivalent. To run docker build as your normal login user, grant that user access:
$ sudo usermod -aG docker $USERThe group applies to new login sessions. Log out and log in again, or runnewgrp docker in the current shell. Use sudo docker build meanwhile. Run docker version to confirm access to both Client and Server. Alternatively, keep your user out of the group and prefix Docker commands withsudo, including sudo docker build -t hello:latest . in the Quickstart. See Docker's user access guidance.
Without buildx, Ubuntu's docker.io uses the legacy builder and prints a harmless buildx deprecation notice. On Ubuntu 24.04, install docker-buildx to remove it with sudo apt-get install -y docker-buildx. The package is available inUbuntu's Noble archive.
2. Install the daemon
The site installer has the release public key built in and verifies every download with it. Download it from the site, read it, then select the exact release withVOXELTRON_VERSION=0.1.3:
$ curl -fsSLo install.sh https://voxeltron.dev/install.sh
$ sudo env VOXELTRON_VERSION=0.1.3 sh ./install.shThe installer creates /etc/voxeltron/voxeltron.toml, initializes gRPC authentication, installs Caddy 2.8 or later or leaves a newer Caddy in place, and enables both caddy and voxeltrond systemd services. Check the services:
$ caddy version
$ sudo systemctl status caddy
$ sudo systemctl status voxeltrond
$ sudo journalctl -u voxeltrond -n 50 --no-pagerThe daemon listens for gRPC on 127.0.0.1:50051. Keep it on loopback and reach it directly on the server or through an SSH tunnel from your laptop.
The installer may also install gnupg, minisign, nftables, Caddy and Caddy's apt repository. It verifies the release first; only minisign, which the check needs, may be installed before that. Caddy's repository is added only if its signing key has the pinned fingerprint 65760C51EDEA2017CEA2CA15155B6D79CA56EA34.
Check the Caddy configuration
Both installers, site/public/install.sh downloaded above and the repository'sscripts/install.sh, recognize the verified stock/etc/caddy/Caddyfile by its checksum. They back that file up to/etc/caddy/Caddyfile.voxeltron-backup, replace it with an admin endpoint onlocalhost:2019 and no sites, and reload Caddy. A repeated install preserves the backup. A custom Caddyfile stays untouched, with a message that existing sites stay andvxl up will report any conflict.
An unmanaged Caddy route error means an existing route, including a catch-all welcome site, already serves the requested domain. Voxeltron refuses to overwrite it. For a custom site, choose another domain or remove only the conflicting route after reviewing it. Run sudo systemctl stop voxeltrond, then run the exactvoxeltrond edge remove-route command printed in the error with sudo. Keep its --index, --expect-sha256 and --yes arguments. Remove the corresponding site from the Caddyfile too so a later reload cannot restore it. Validate and reload Caddy, run sudo systemctl start voxeltrond, then retry the deploy.
3. Enable automatic HTTPS
A domain: route refuses to deploy without an ACME contact email:proxy.acme.email must be set to the contact address for Let's Encrypt. For a test box with no public DNS, use issuer = "internal" instead; see Domains and TLS for local certificate trust. Add email under the existing [proxy.acme] table in/etc/voxeltron/voxeltron.toml. Do not paste a second table header. The file holds the daemon's gRPC signing secret, so do not paste it anywhere. Reading or editing this protected file requires sudo:
$ sudo grep -A4 '^\[proxy.acme\]' /etc/voxeltron/voxeltron.toml
$ sudoedit /etc/voxeltron/voxeltron.tomlFor a non-interactive alternative to sudoedit, run this once to insert the email under the existing table:
$ sudo sed -i '/^\[proxy.acme\]/a email = "[email protected]"' /etc/voxeltron/voxeltron.tomlThe resulting table is:
[proxy.acme]
issuer = "acme"
email = "[email protected]"
directory_url = "https://acme-v02.api.letsencrypt.org/directory"Validate the edited file, then restart the daemon:
$ sudo voxeltrond config validate
$ sudo systemctl restart voxeltrond4. Add the server on the server itself
Run these commands on the server as your normal login user. The installer also installsvxl. This profile connects directly to loopback and needs no SSH login to itself:
$ sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | vxl server add prod --host 127.0.0.1 --runtime docker --auth-token-stdin
$ vxl server use prod
$ vxl server inspect prodExpect Transport: plaintext over loopback. The bearer token authenticates calls without TLS or an insecure override. Keep gRPC bound to 127.0.0.1:50051. Only the mint command uses sudo, so the profile belongs to your login user. Run later vxl commands as that same user.
Tokens expire after one hour by default. This pipeline requests 86400 seconds, the default maximum of one day. Repeat it when the token expires. The token travels through stdin instead of argv. Keep it secret. VXL_TOKEN is also supported when another tool already supplies the token through the environment.
5. Create the app
If you will operate from your laptop, follow From your laptop for CLI setup and manifest placement. Build the image on the server, then run steps 6 to 8 on the laptop.
On the server, make a directory with a small web app, a Dockerfile and a manifest. Replace hello.example.com with your DNS name:
$ mkdir hello && cd helloapp.py answers /healthz and checks Postgres on every other request:
import os
from http.server import BaseHTTPRequestHandler, HTTPServer
import psycopg
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
self.respond(send_body=True)
def do_HEAD(self):
self.respond(send_body=False)
def respond(self, send_body):
if self.path == "/healthz":
body = b"ok\n"
else:
with psycopg.connect(os.environ["DATABASE_URL"], connect_timeout=3) as conn:
with conn.cursor() as cur:
cur.execute("select 1")
conn.commit()
body = b"hello from voxeltron; postgres ok\n"
self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
if send_body:
self.wfile.write(body)
HTTPServer(("0.0.0.0", int(os.environ.get("PORT", "8080"))), Handler).serve_forever()Dockerfile:
FROM python:3.12-slim
RUN pip install --no-cache-dir "psycopg[binary]==3.2.3"
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]voxeltron.yaml describes the app and the database:
name: hello
app:
image: hello:latest
port: 8080
health: /healthz
domain: hello.example.com
services:
db:
type: postgres
disk: 1GBBuild the image on the server so the daemon can start it without a registry:
$ docker build -t hello:latest .Do not set DATABASE_URL yourself. The postgres service creates the credentials in the daemon's secret store and injects DATABASE_URL into the app.
6. Deploy
Check the translated request first. It contains the product key and the app image:
$ vxl up --dry-runThen deploy:
$ vxl up --server prod --yesvxl up creates the Postgres volume, starts both components, routes the domain through Caddy and requests a certificate. The first deploy takes a few minutes because the Postgres image must be pulled.
7. Check it
Replace hello.example.com in the manifest and commands with your domain. Before DNS is ready, check the route on the server withcurl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' -H 'Host: hello.example.com' http://127.0.0.1/. This sends a GET and prints the status code and redirect URL. For a public domain, expect308 https://hello.example.com/. The route is live, and HTTPS takes over once DNS and the certificate are ready. For a name Caddy will not get a public certificate for, such as hello.test, expect 200 directly from the app. Public HTTPS needs the name to resolve to the server, ports 80 and 443 to be reachable and the certificate to be issued.
$ curl -fsS https://hello.example.com/healthz
ok
$ curl -fsS https://hello.example.com/
hello from voxeltron; postgres ok
$ vxl app status --name hello --server prodIf the certificate is not ready yet, check DNS and port 80, then watch the daemon:sudo journalctl -u voxeltrond -f.
health=healthy means the deployment has passed its configured health check. It appears once that check passes.
8. Remove it
vxl down removes app containers and routes and deletes local up state only after the daemon confirms. Service data, including Postgres volumes, is kept and reattached by the next vxl up. Removing a service from the manifest also keeps its data.
$ vxl down --server prod --yesTo permanently delete retained service data, confirm the volume list and sizes:
$ vxl down --server prod --purge-dataAdd --yes to skip confirmation. Project deletion removes metadata and routes; purge retained data before deleting the project.
From your laptop
On an Apple silicon Mac, the same signed site installer installs vxl only. The default /usr/local/bin usually needs sudo; the installer invokes sudo when that destination is not writable. To avoid sudo for the binary installation, create a directory you own and add it to PATH:
$ mkdir -p "$HOME/.local/bin"
$ curl -fsSLo install.sh https://voxeltron.dev/install.sh
$ env VOXELTRON_VERSION=0.1.3 VOXELTRON_INSTALL_BIN_DIR="$HOME/.local/bin" sh ./install.sh
$ export PATH="$HOME/.local/bin:$PATH"Read install.sh before running it. Add the PATH export to ~/.zshrc for future shells. Install minisign first with brew install minisign if it is missing; the installer refuses to continue without it on macOS.
Install vxl on the laptop first. Replace 203.0.113.10 andadmin below with your server address and SSH user. That user must have SSH key login and permission to run the token mint command with sudo. The pipeline needs noninteractive sudo for token minting. If sudo requires a password, mint the token in an interactive server session and supply it through stdin on the laptop instead. Voxeltron uses your local SSH agent or keys in ~/.ssh. Use --key for a specific key.
Through your provider's console or an existing trusted server session, run this on the server to read its Ed25519 host key fingerprint:
$ ssh-keyscan -t ed25519 localhost 2>/dev/null | ssh-keygen -lf -Voxeltron accepts the SHA256 fingerprint of any host key type returned byssh-keyscan, including RSA, ECDSA and Ed25519. If the server has no Ed25519 key, use -t rsa or -t ecdsa in the console command instead. Pin the verified fingerprint with --host-key-fingerprint SHA256:... onvxl server add. An unknown host error prints the presented fingerprints and a pin command.
On the laptop, OpenSSH also needs the verified key in ~/.ssh/known_hosts. Run ssh [email protected], compare the fingerprint it prints on first connect with the fingerprint obtained from the console for that key type, and answer yesonly if they match. This saves the key to ~/.ssh/known_hosts. Confirm SSH works, then exit back to the laptop before running the pipeline below.
Alternatively, --accept-host-key explicitly enables trust on first use. This records the first key presented without independently verifying who owns it. The example below uses that alternative. Do not combine the two flags. Later connections verify the recorded key strictly and reject a changed key.vxl bootstrap uses the same --accept-host-key and--host-key-fingerprint options. When replacing a profile, supply its connection options and token again.
The token pipeline must pass only the token to stdin. Do not add 2>&1 to the SSH half or mix diagnostics or other output into the pipe.
$ ssh [email protected] sudo voxeltrond token mint --config /etc/voxeltron/voxeltron.toml --subject operator --ttl 86400 | \
vxl server add prod --host 203.0.113.10 --user admin --ssh-tunnel \
--runtime docker --accept-host-key --auth-token-stdin
$ vxl server use prod
$ vxl server inspect prodExpect Transport: SSH tunnel to 203.0.113.10, plaintext inside. SSH protects the connection to the server, and the bearer token authenticates gRPC inside it. Keep the management port on loopback. The Quickstart's image build runs on the server, where the daemon needs the image. A laptop build alone does not place it there.
What runs where
- On the server: the app source, Dockerfile and
docker build. The daemon needs the image locally. - On the laptop:
voxeltron.yamland everyvxlcommand, includingvxl up,vxl app statusandvxl down. Run them from the directory containing the manifest.
After creating the app in step 5 of the Quickstart, copy its manifest from the server into your laptop's app directory, or keep the project in git on both machines:
$ scp [email protected]:~/hello/voxeltron.yaml .Next
- First deployment covers image and git deploys with
vxl deploy. - Databases covers
vxl db create, connection strings, backups and restores. - Domains and TLS covers Caddy, certificates and the optional Cloudflare edge.