Skip to main content

Change an installed stack's template inputs

PUT 
/stacks/:name/config

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

Example request
curl --request PUT \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/stacks/{name}/config"

Changes the values of some of the stack's template inputs. Every value is checked with the rules previewTemplateInstall uses, before anything is stored: a value that does not fit its kind, a path that is not absolute, a string input emptied that is not optional, or a device input given a different value (its mapping is in the Compose file, so it is changed there) is refused with 400 invalid_template_input, whose details.input names the input; a port input changed to a port that a container publishes or is configured to publish, that another stack's Compose file publishes, or that the host listens on, is refused with 409 no_free_port and is never moved to another port (the stack's own ports are not taken); a .env that would define a variable Docker takes from the daemon's environment is refused with 400 invalid_stack_env. A refusal changes nothing. Otherwise the new .env is sealed into the stack's row and the stack's .env file is regenerated from it: only the lines of the inputs that changed are rewritten and every other line is kept. If writing the file fails the row is put back as it was. docker-compose.yml is never regenerated from the template, so a manual edit of it stays, and nothing is restarted: startStack makes the change take effect. An input without an entry keeps its value. An empty entry takes the input's default, as in an install, and so clears an optional string input. A secret with no entry or an empty one keeps the sealed value; a non-empty one replaces it; one named in generate gets a newly generated value (48 hexadecimal characters), and naming one that is not a secret, or that also has a value, is refused with 400 invalid_template_input. The answer is getStackConfig's, with the values as they are now. The other errors of getStackConfig apply; 503 docker_unavailable is answered only when a port was changed, since the check needs Docker.

Request​

Responses​

The stack's inputs after the change.