Skip to main content

Preview installing a catalog template

POST 
/templates/:id/preview

Required role: admin. Only an account or token with the admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/templates/{id}/preview"

Resolves the template's inputs the way an install would, without creating a stack or writing any file of the template: paths default to the template's own default or, with none, to the existing share of the input's role (/mnt/user/<role>) and list the existing shares as suggestions; a port that a container publishes or is configured to publish, running or stopped, that an existing stack's Compose file publishes (resolved with its .env, whether or not the stack was started), or that the host listens on resolves to the next free port above it, with the port asked for in requestedValue; a timezone with no value takes the host's; a device input with role gpu lists the host's render devices (/dev/dri/renderD*) as suggestions. A secret is never given a value here: it is marked generated and is generated by the install. The privilege summary is computed from the Compose content with these values substituted — privileged mode, host networking, the host PID or cgroup namespace, device cgroup rules, added capabilities, disabled or replaced confinement, extra groups, the Docker socket and host paths outside the pool and cache (the cache itself and Docker's data-root on it count as outside) — never from anything the template declares. compose is the file an install would write. A path input with no value, no default and no existing share to default to, a port input with neither value nor default, and a string input with no value and no default are listed with required: true and an error, so a form shows every field and installTemplate refuses them (a string input the template marks optional may be left empty and is written to .env with an empty value). An input that is not the template's or a value that does not fit its kind is refused with 400 invalid_template_input, and so is a setting that does not fit (networkMode, cpus, memoryMiB, extraParams); the error's details.input names the input or setting it is about. The container settings of the request (networkMode, restart, cpus, memoryMiB, extraParams) are written into compose, and warnings lists what they could not carry out; a name that is not a valid stack name with 400 invalid_stack_name; an unknown template with 404 template_not_found; a catalog entry that fails the template rules with 422 template_invalid (an input is written to the stack's .env under its name, so one named PATH, HOME, XDG_RUNTIME_DIR, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH or DOCKER_TLS_VERIFY, which Docker takes from the daemon's environment, fails them); a GPU the host cannot give to a container (no render group) with 409 gpu_unavailable; no free port above a conflicting one with 409 no_free_port, and the same code, never moving the port, for a host port extraParams publishes that is taken; Docker not reachable, which the port check needs, with 503 docker_unavailable. The check also reads the ports of every existing stack with docker compose config; a stack whose ports cannot be read refuses the request (stack_action_failed) instead of the port being assumed free. Reading a stack's ports also regenerates, from the stack's row, any of its docker-compose.yml, .env or meta.json that is missing from its directory; a file that exists is never changed, and a stack removed meanwhile is skipped. installTemplate does the same.

Request​

Responses​

What an install would do.