Skip to main content

Create a Compose stack

POST 
/stacks

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/stacks"

Stores the stack's row (.env sealed under the machine key) and generates docker-compose.yml, .env and meta.json into the directory named after the stack, then checks the result with docker compose config. Nothing is started. Refused with 409 stack_exists when a stack of that name exists. A directory of that name already under the stacks directory (what a removed stack's own files left behind) is used as it is, and only the three generated files are written into it; it is refused with 409 stack_dir_exists when it holds a docker-compose.yml, which is never overwritten. A name that is not 1 to 63 lowercase letters, digits, - or _, starting with a letter or digit, is refused with 400 invalid_stack_name before anything is touched. A Compose file that docker compose config rejects is refused with 400 invalid_stack, and leaves no row and no generated file behind. A .env that defines one of the variables Docker needs from the daemon's environment (PATH, HOME, XDG_RUNTIME_DIR, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY) is refused with 400 invalid_stack_env before anything is stored or written, so Docker always runs with the daemon's own values for them.

Request​

Responses​

The created stack.