Voxeltron Docs
Get Started Free

Your First Deployment

Let's take your app from zero to live — with TLS, a custom domain, and zero downtime. This guide covers deploying from a Docker image and from a GitHub repo.

All of these commands run inside the TUI. Launch it with voxeltron and use d for Deploy, or run them directly from the CLI.

Option A: Deploy a Docker Image

The simplest path — if you already have a Docker image:

1

Create a new service

$ voxeltron deploy \
    --name my-app \
    --image nginx:alpine \
    --port 80 \
    --domain my-app.example.com

Voxeltron will:

  • Pull the image from Docker Hub (or your private registry)
  • Start the container
  • Register the domain with the Pingora reverse proxy
  • Issue a TLS certificate via Let's Encrypt
2

Watch the deploy

✓ Pulling image nginx:alpine...
✓ Starting container my-app-v1...
✓ Health check passed (HTTP 200 on /)
✓ TLS certificate issued (0.3s)
✓ Route registered: my-app.example.com → my-app-v1:80
✓ Live at https://my-app.example.com

Option B: Deploy from a Git Repository

For source-to-image builds using Nixpacks (zero config) or Railpack:

1

Connect your repository

$ voxeltron deploy \
    --name my-node-app \
    --source github.com/you/my-node-app \
    --branch main \
    --domain my-node-app.example.com

Voxeltron will auto-detect your language and build system. No config file needed.

2

Watch the build

→ Cloning github.com/you/my-node-app (main)...
→ Detected: Node.js 20 via Nixpacks
→ Installing dependencies (npm ci)...
→ Running build (npm run build)...
→ Image built in 34s · 143MB
→ Zero-downtime swap via Pingora hot-reload...
✓ Deployed! https://my-node-app.example.com
3

Set up automatic deploys on git push

$ voxeltron service webhook my-node-app

Webhook URL: https://my-server.example.com/_vx/hooks/abc123xyz
Secret: (shown once — copy it now)

Add this webhook URL to your GitHub/GitLab/Gitea repo. Every push to main will trigger a zero-downtime redeploy.

Set Environment Variables

Inject secrets securely — they're encrypted at rest and never appear in logs:

$ voxeltron env set my-app \
    NODE_ENV=production \
    API_KEY=super-secret-value \
    DATABASE_URL="postgresql://..."
Environment variables are encrypted with AES-256-GCM using a key derived with Argon2id. The plaintext is never written to disk or logged.

Check Logs

# Live log tail
$ voxeltron logs my-app --follow

# Search logs
$ voxeltron logs my-app --search "error" --lines 100

# Or use the TUI: select service, press 'l'

Check Service Status

$ voxeltron status my-app

Service: my-app
  Status:  running
  Image:   my-node-app:main-abc1234
  Uptime:  2h 14m
  CPU:     0.3%
  Memory:  128MB / 512MB
  Restart: 0 times
  Domain:  https://my-node-app.example.com (TLS valid)

Roll Back a Deploy

Made a bad deploy? Roll back in one command:

$ voxeltron rollback my-app

Deploy history:
  → v3  main-abc1234  2026-02-20 09:14  (current)
     v2  main-def5678  2026-02-19 22:03
     v1  main-ghi9012  2026-02-19 14:55

Roll back to v2? [y/n]: y
✓ Zero-downtime rollback to main-def5678 complete

What's next?

🗄️
Add a Database
Provision Postgres, MySQL, Redis, or MongoDB in under 30 seconds.
🔐
Custom Domains & TLS
Configure wildcard domains, DNS-01 challenges, and custom cert authorities.
🤖
Enable the AI Panel
Connect to Claude, GPT-4, Gemini, or Ollama and let the AI manage your infra.
🧩
Install Plugins
Browse the plugin marketplace and extend Voxeltron with WASM plugins.
← Installation
Databases →