Skip to main content

Remove a Compose stack

DELETE 
/stacks/:name

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

Example request
curl --request DELETE \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  "https://$HOSERVA_HOST:8008/api/v1/stacks/{name}"

Runs docker compose down for the stack (its containers and networks are removed; named volumes are kept), deletes its generated docker-compose.yml, .env and meta.json, and then its row; the stack's directory goes too if nothing else is in it, so the name can be used again and a file the stack keeps there stays. Taking the stack down does not need its .env. docker compose down removes every container and network of the stack's Compose project name, and with --volumes its named volumes, whichever file or directory they were started from. So before docker runs, every container of that project must be one Compose started from the stack's own directory: a project of the same name that something else runs (a hand-run ~/immich/compose.yml is project immich) is refused with 409 stack_project_shared, whether or not the stack has its .env and whether or not appdata is deleted. Since that cannot be checked otherwise, a remove is also refused, as any docker failure is, when the project's containers cannot be listed (503 docker_unavailable when Docker is not reachable). Appdata is deleted only when deleteAppdata is explicitly true: then the stack's named volumes are removed with docker compose down --volumes, each bind-mount directory of the stack's containers that lies strictly inside an appdata location (the cache disk's appdata directory) and is used by no other container is deleted, and so is the stack's whole directory, before the row. Nothing is deleted if one of the stack's containers is still there after docker compose down. That needs the array running, like a container remove that deletes appdata: refused with 409 array_stopped (or 503 array_state_unknown) before anything is changed, with 409 appdata_unavailable when no appdata location is known, and with 409 appdata_shared when a directory is used by another container or another container binds a place inside the stack's directory. A name that is not a valid stack name is refused with 400 invalid_stack_name before anything is touched. A docker compose down that fails, or a directory that cannot be deleted, leaves the row in place so the remove can be retried.

Request​

Responses​

The stack was removed.