Image needs root capabilities

Voxeltron drops every Linux capability from app containers. An image whose entrypoint changes file ownership or switches user exits at startup, and the deploy fails withVXL-CAP-001. App containers also have a read-only root filesystem; an image that writes outside /tmp, /var/tmp, /run and itsapp.writable_paths fails with VXL-FS-001. The stocknginx image hits one or the other, depending on whether/var/cache/nginx is writable.

What you see

health check failed: VXL-CAP-001: This image needs root capabilities, which Voxeltron drops.
For nginx, use nginxinc/nginx-unprivileged and listen on port 8080. Run `vxl app fix` to see a fix plan.
evidence: nginx: [emerg] chown("/var/cache/nginx/client_temp", 101) failed (1: Operation not permitted)

The evidence lines are the log lines that matched: a chown, setuid,setgid, setgroups or initgroups call refused withOperation not permitted. vxl status and the TUI deployment view show the same id.

A read-only write looks like this:

health check failed: VXL-FS-001: This image writes outside its writable paths, and the root filesystem is read-only. ...
evidence: nginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system)

Fix it with vxl app fix

From the directory that holds voxeltron.yaml, see the plan first. This changes nothing:

$ vxl app fix --server prod

For the stock nginx image the plan shows each change as a diff:

  • app.image: nginx:<tag> becomes nginxinc/nginx-unprivileged:<tag>. The tag is checked on Docker Hub; if it is not published, the plan uses the nearest tag and says so.
  • app.port: 80 becomes 8080.
  • A FROM nginx line in the app's Dockerfile is rewritten the same way.
  • listen 80 lines, and a pid file outside /tmp, in nginx configs in the build directory are rewritten. Anything it cannot rewrite safely is listed as a manual step.

Apply it when the plan looks right:

$ vxl app fix --server prod --apply

--apply asks you to confirm (or pass --yes), writes the files, redeploys with vxl up, and checks that the app is healthy with a URL. If the redeploy or the check fails, your files are restored, and a failed check rolls the app back with vxl rollback. Running vxl app fix again reports that there is nothing to fix.

Other images

For VXL-FS-001, add the directory from the evidence line underapp.writable_paths in voxeltron.yaml and run vxl upagain. See the manifest reference for sizes and limits.

There is no automatic fix for other images yet; vxl app fix shows the diagnosis and the evidence. Use a variant of the image that runs as a non-root user, or remove the entrypoint step that changes ownership or user. Capabilities stay dropped; there is no setting to add them back.

For an image deployed with vxl deploy and no manifest, redeploy it yourself, for example:

$ vxl deploy nginxinc/nginx-unprivileged:1.27-alpine --name web --server prod --internal-port 8080 --wait