Introduction

What is Voodu?

Voodu is a Heroku-shaped, Kubernetes-honest deploy tool you run on your own boxes.

One HCL file describes the running system. voodu apply reconciles it: builds, ships, routes, swaps. No bare repo, no git push, no plugin sprawl — apps, ingress with TLS, and stateful services that actually back themselves up.

app "myapp" "web" {
  image    = "ghcr.io/myorg/myapp:latest"
  replicas = 3

  env = {
    PORT     = "8080"
    NODE_ENV = "production"
  }

  health_check = "/healthz"
  host         = "myapp.example.com"

  tls {
    email = "ops@example.com"
  }
}

voodu apply -f voodu -r prod-1
# ✓ apply complete in 11.8s
# ✓ https://myapp.example.com  ·  3/3 healthy

Why Voodu?

• One file, one command. No git push, no bare repo, no commit ceremony. Edit, save, voodu apply.
• Declarative apply, not git-push. Diff shows the plan. Apply reconciles. Upsert-only by default — --prune is the explicit opt-in (scoped per (scope, kind)).
• Stateful services are first-class. Postgres, Mongo, Redis (+ sentinel) declared like apps. Plugins ship backup, replicas, and test-restore.
• TLS out of the box. Add tls {} and Voodu cuts a Let's Encrypt cert via Caddy. On-demand wildcards.
• k8s shape, not k8s ops. Same reconciliation loop, none of the CNI/Helm/operator bill.
• Laptop or CI, same command. The official GitHub Action is a thin wrapper around voodu apply — nothing to learn twice, and no drift between how you deploy and how the pipeline does.
• 100% self-hosted, Elastic License 2.0. Single Go binary, embedded etcd, no cloud tier, no telemetry.

Where apply runs

voodu apply is the entire deploy. Where you run it from is your choice, and both places run the same command.

From your machine. Edit, save, apply — nothing else in the loop:

voodu apply -f voodu -r prod-1

From CI. The clowk-in/voodu-gh action installs the CLI, prepares SSH, and calls that same voodu apply:

      - uses: actions/checkout@v4

      - uses: clowk-in/voodu-gh@v1
        with:
          manifests: infra/web.voodu

A push can trigger the workflow, but the deploy underneath is still a declarative apply — there is no bare repo, no receive hook, no server-side git. That is what makes the two interchangeable: a laptop and a workflow produce the same result, so you can adopt CI gradually and still apply by hand when you need to.

Pull requests get the plan instead of the deploy. dry-run: true runs voodu diff and changes nothing, so a reviewer reads what would happen before the merge makes it happen.

Inputs, concurrency, and the security posture an SSH deploy key demands: GitHub Actions.

Quickstart

1. Install Voodu on your laptop
2. Bootstrap a remote
3. Ship your first app
4. Hand the apply to CI — optional, and the same command

Manifest reference

The full HCL surface, kind by kind:

• Overview — (scope, name), blocks, references
• app — web services, workers, replicas
• ingress + tls — Caddy routes + ACME
• postgres, redis — stateful with backup
• job / cronjob — one-shots and schedules
• config & secrets — out-of-band env

CLI

Six verbs cover ~95% of day-to-day: