Skip to main content

Install a catalog template as a stack

POST 
/templates/:id/install

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}/install"

Resolves the inputs exactly as previewTemplateInstall does, and generates each secret that has no value of its own (48 hexadecimal characters). A port that is taken is moved to the next free port and reported in the result's requestedValue, never refused. Taken means what previewTemplateInstall lists, including the ports of stacks installed earlier that were never started, so two installs in a row are given different ports; installs run one at a time. Reading the ports of existing stacks regenerates their missing generated files from their rows, as previewTemplateInstall describes. A port that something other than Hoserva takes after the install is not checked. Then it creates the stack as createStack does: the stack's row records the template's source, id and revision, and docker-compose.yml (the template with its x-hoserva block kept, plus the /dev/dri device and the host's render group for a GPU that was chosen), .env (every input; secrets only here) and meta.json are generated and checked with docker compose config. Nothing is started. The result carries the privilege summary, so a template that asks for privileged mode, the Docker socket or any other kind previewTemplateInstall lists is reported with its install. The stack errors of createStack apply (409 stack_exists, 409 stack_dir_exists, 400 invalid_stack), as do those of previewTemplateInstall. An input that needs a value and has none is refused with 400 invalid_template_input whose details.input names it, and a networkMode that names a network that does not exist with 409 network_missing (the message holds the docker network create command); nothing is written in either case. A request that carries planDigest is refused with 409 template_changed when the plan this install would write has another digest, because the catalog was refreshed or another source supplied the template since the preview; nothing is created, and a new preview shows what the template is now.

Request​

Responses​

The installed stack and what it was installed with.