voxeltron ボクセルトロン
Install

Domains & TLS

Voxeltron provides automatic HTTPS for every app via ACME/Let’s Encrypt, with support for custom domains, wildcard certificates, and zero-downtime renewal.

Overview

Every app deployed on Voxeltron gets a TLS certificate automatically. The daemon handles the full lifecycle — issuance, verification, installation, and renewal — so you never touch a certificate file.

Automatic HTTPS

ACME/Let’s Encrypt certificates issued and renewed without intervention.

Custom Domains

Point any domain at your server and Voxeltron provisions a certificate automatically.

Wildcard Certs

Secure *.yourdomain.com with a single DNS-01 challenge.

Self-Signed Fallback

Auto-generated self-signed certs for local dev and internal networks.

ACME / Let’s Encrypt

Voxeltron uses the ACME protocol to obtain trusted TLS certificates from Let’s Encrypt (or any ACME-compatible CA). The daemon acts as an ACME client, handling challenges and key management internally.

HTTP-01 Challenge Flow

The default verification method is the HTTP-01 challenge. Here’s how it works:

  1. Voxeltron requests a certificate for the domain from the ACME directory.
  2. The CA responds with a token and a challenge URL.
  3. The daemon places the token at http://<domain>/.well-known/acme-challenge/<token>.
  4. The CA fetches the token over HTTP to verify domain ownership.
  5. On success, the CA issues a signed certificate and Voxeltron installs it immediately.
Port 80 must be reachable from the internet for HTTP-01 challenges. The daemon automatically redirects all other HTTP traffic to HTTPS.

Staging vs Production

During setup, use the Let’s Encrypt staging directory to avoid rate limits. Staging certificates are not trusted by browsers but are functionally identical for testing. 

# Staging (for testing)
acme_directory = "https://acme-staging-v02.api.letsencrypt.org/directory"

# Production (default)
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"

Auto-Renewal

A background task checks certificate expiry daily. Certificates are renewed when they have fewer than 30 days remaining — well within the 90-day Let’s Encrypt lifetime. Renewal uses the same challenge method as initial issuance and requires zero downtime.

Custom Domains

Add a custom domain to any app with a single command. Voxeltron verifies ownership and provisions a certificate.

Adding a Domain

voxeltron domains add myapp.example.com --app my-app

DNS Configuration

Point your domain at the Voxeltron server using one of these DNS record types:

A Record

Point the domain directly at your server’s IP address. Best for apex domains. 

myapp.example.com.  A  203.0.113.10
CNAME Record

Alias to your Voxeltron hostname. Best for subdomains. 

myapp.example.com.  CNAME  voxeltron.example.com.

Verification

After adding a domain, Voxeltron verifies DNS resolution before requesting a certificate. Check status with: 

voxeltron domains list --app my-app

DOMAIN                  STATUS       CERTIFICATE
myapp.example.com       verified     valid (expires 2026-05-20)
staging.example.com     pending      awaiting DNS

Wildcard Certificates

Wildcard certificates cover all subdomains under a single domain, e.g. *.yourdomain.com. They require the DNS-01 challenge method since the CA must verify control of the entire zone.

DNS-01 Challenge

Instead of placing a token on a web server, DNS-01 requires you to create a TXT record:

  1. Voxeltron requests a wildcard certificate from the ACME directory.
  2. The CA returns a challenge value.
  3. You (or an automated DNS provider integration) create a TXT record at _acme-challenge.yourdomain.com.
  4. The CA queries DNS to verify the record.
  5. On success, a wildcard certificate is issued for *.yourdomain.com.
voxeltron domains add "*.yourdomain.com" --app my-app --challenge dns-01
For fully automated DNS-01 challenges, configure a supported DNS provider in your voxeltron.toml. Manual TXT record creation is supported as a fallback.

Self-Signed Certificates

For local development and internal networks where public CA validation isn’t possible, Voxeltron auto-generates self-signed certificates on first boot. These provide encrypted connections without external dependencies. 

[tls]
mode = "self-signed"   # Options: "acme" (default), "self-signed", "manual"
Self-signed certificates trigger browser warnings. For local development, add the generated CA to your system trust store, or use curl --insecure for API testing.

Certificate Storage

All certificates and private keys are stored on disk in the Voxeltron data directory: 

/var/lib/voxeltron/certs/
  ├── myapp.example.com/
  │   ├── cert.pem
  │   ├── key.pem
  │   └── chain.pem
  └── acme-account.json

The renewal background task runs daily and checks every certificate’s expiry. Certificates within 30 days of expiration are renewed automatically. The task logs all renewal attempts to the audit log.

Private keys are stored with 0600 permissions and are readable only by the voxeltron system user. Back up the certs/ directory alongside your regular data backups.

Configuration

TLS settings are defined in voxeltron.toml: 

[tls]
acme_email = "admin@example.com"
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"

# Optional: DNS provider for DNS-01 challenges
# dns_provider = "cloudflare"
# dns_api_token = "$${CLOUDFLARE_API_TOKEN}" 

# Optional: certificate storage path (default: /var/lib/voxeltron/certs)
# cert_path = "/var/lib/voxeltron/certs"

# Optional: renewal check interval in hours (default: 24)
# renewal_interval = 24
← Plugins
Configuration →