Quick start

You'll need a small Linux box, optionally a domain pointed at it, and a Git repository to deploy.

Before you begin

Make sure you have:

• A Linux VPS (Debian 12 / Ubuntu 22.04+ recommended). VAC's control plane idles under 200 MB RAM excluding the database, so a 1–2 vCPU box leaves plenty for your apps.
• Root or sudo access.
• Docker Engine with the Compose v2 plugin. The installer will offer to install Docker for you if it's missing.
• (Optional but recommended) a domain, with a vac.<domain> record and a wildcard *.<domain> A record pointing at the box. Without a domain the dashboard stays on plain HTTP at http://<host>:9393.

Install the VAC control plane

SSH into your VPS and run the installer. It pulls the prebuilt compose stack (vac-db, vac-api, vac-proxy), generates secrets, and brings everything up.

curl -sSL get.vac.vojir.io | sudo sh

Run it in a terminal and it walks you through a short setup — domain, managed services, sudo-free access — and shows a summary before touching the host. Piped without a terminal (CI, provisioning) it runs unattended with safe defaults.

To pin a version and set the domain up front (which skips the matching prompts):

VAC_VERSION=v0.5.0 VAC_DOMAIN=example.com sh install.sh

See Installation for every option, flag, and what gets written where.

Point DNS at the box

If you set a domain, add two records so the dashboard and your apps resolve. Both point at the same host IP:

vac      IN  A   203.0.113.42    ## the dashboard → https://vac.example.com
*        IN  A   203.0.113.42    ## every app → https://{app}.example.com

Caddy (bundled as vac-proxy) requests certificates from Let's Encrypt on demand the first time each hostname is hit — no manual cert wrangling. The first dashboard load may take a few seconds while the cert is issued.

Create the first operator account

The installer prints a one-time setup link in its summary, along with the dashboard URL. Open it and create your admin account:

• With a domain: https://vac.example.com
• Without: http://<host>:9393

You can enable TOTP two-factor auth right away — VAC uses it both for login and as step-up confirmation for destructive actions.

Connect your first repository

In the dashboard, click New app and paste a Git URL. VAC accepts:

• Public HTTPS — https://github.com/you/app.git, no credentials needed.
• SSH — git@github.com:you/app.git. VAC mints a per-app deploy key; copy its public half into your repo's deploy keys.

Pick a branch (defaults to main). VAC detects how to build the repo automatically — a Compose file, a Dockerfile, or a recognised framework. See Build settings for the detection order and how to override it.

Deploy

Hit Deploy. VAC clones the repo, builds the stack, brings it up, and gates the rollout on a Caddy health check before flipping the app to running. Build and runtime logs stream live into the dashboard the whole time.

Deploy on every push

Want push-to-deploy? Each app exposes an inbound webhook. Add the webhook URL to your repo's settings, then create a deploy trigger (e.g. push to main, or tags matching v*). VAC validates the signature and redeploys on matching events. See Webhooks.

What's next