Skip to content
vops

Deploy an application

A repository deployment has four visible stages: validate the manifest, obtain an image, create a plan, and verify the applied result. vops never builds an application image on the target VPS or the developer’s workstation.

Before you start

You need:

  • a repository with a valid flui.yaml;
  • a reachable host in vops host list;
  • an image already published, or a GitHub repository whose workflow vops can trigger;
  • values for every declared runtime setting or secret.

Validate first:

Terminal window
vops spec validate flui.yaml
vops app preflight web-1

Both commands are non-mutating.

Obtain the application image

If you already have an immutable image reference, keep it for the plan:

ghcr.io/acme/my-api:4f3c2a1

To use GitHub Actions, let vops write a reviewable workflow:

Terminal window
vops build setup
git diff -- .github/workflows/vops-build.yml

You decide whether to commit and push that file. Once the workflow exists on GitHub, trigger it and wait for the published image reference:

Terminal window
vops build run --wait
vops build status

The GitHub PAT is read from the local encrypted store, VOPS_GITHUB_TOKEN or the --token input. A private container package may also require a read-only registry token at apply time.

Create the immutable plan

Terminal window
vops deploy plan \
  --spec flui.yaml \
  --host web-1 \
  --image ghcr.io/acme/my-api:4f3c2a1 \
  --domain api.example.com

Planning writes a versioned artifact under .vops/plans/ and changes nothing on the host. Review:

  • application and target host;
  • component images;
  • declared secrets;
  • endpoints and exposure;
  • domain, TLS and optional access gate;
  • warnings and coexistence notes.

Do not put secret values into the manifest or plan file. Supply declared values with --set KEY=value; vops keeps them outside the immutable public plan material.

Apply exactly what you reviewed

Terminal window
vops deploy apply --plan <plan-id> --yes

At apply time vops derives the plan again. If the manifest, host or relevant inputs no longer produce the approved plan, it refuses as stale rather than silently deploying something else.

For a private registry:

Terminal window
VOPS_REGISTRY_TOKEN=... \
  vops deploy apply \
  --plan <plan-id> \
  --registry-user <user> \
  --yes

Use a token scoped to pulling packages.

Verify from the workstation

Terminal window
vops deploy verify --app my-api

Verification checks the host units and containers, then performs the applicable DNS and HTTP or HTTPS checks from the workstation. A successful upload is not enough evidence that a public application is reachable.

If verification fails:

Terminal window
vops app status my-api
vops app logs my-api --lines 200
vops ingress status web-1

See Troubleshooting for a fuller diagnostic path.

The shorter interactive path

For direct human use, vops app deploy combines preflight, plan rendering and approval:

Terminal window
vops app deploy -f ./flui.yaml --host web-1 --image <image>
vops app deploy -f ./flui.yaml --host web-1 --image <image> --yes

Use the explicit deploy plan → apply → verify path when the plan must be reviewed, handed between tools or approved for an agent session.