Update Stack

Update a stack compose file and optionally restart

PUT /api/stacks/{name}/compose

Update Without Restart

curl -X PUT "https://your-dockhand-instance.com/api/stacks/my-app/compose?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_token" \
  -d '{
    "content": "version: '\''3.8'\''\nservices:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"8080:80\"",
    "restart": false
  }'

Update Without Restart

{
  "success": true
}

Path Parameters

name · string · required

Stack name (URL-encoded)

Query Parameters

env · string · required

Environment ID where the stack exists

Body Parameters

content · string · required

Updated Docker Compose file content (YAML)

restart · boolean · default: false

Whether to restart the stack after updating. If true, runs docker compose up -d --force-recreate.

composePath · string

Custom path for the compose file (for updating file location)

envPath · string

Custom path for the .env file (for updating file location)

moveFromDir · string

Original directory when moving/relocating stack files

oldComposePath · string

Previous compose file path when renaming

oldEnvPath · string

Previous env file path when renaming

Response

success · boolean

Whether the update succeeded

error · string

Error message if update failed

When restart=true, the endpoint uses Server-Sent Events (SSE) and includes:

output · string

Docker Compose output from the restart operation

Behavior

• If restart=false, only saves the compose file without restarting containers
• If restart=true, uses --force-recreate to ensure environment variable changes are applied
• Custom paths allow relocating stack files to different directories
• The stack must exist and be managed by Dockhand

Update Without Restart

curl -X PUT "https://your-dockhand-instance.com/api/stacks/my-app/compose?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_token" \
  -d '{
    "content": "version: '\''3.8'\''\nservices:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"8080:80\"",
    "restart": false
  }'

Update Without Restart

{
  "success": true
}

Get Current Compose File

Before updating, you can retrieve the current compose file:

curl -X GET "https://your-dockhand-instance.com/api/stacks/my-app/compose?env=1" \
  -H "Cookie: auth_token=your_token"

Response:

{
  "content": "version: '3.8'\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"8080:80\"",
  "stackDir": "/data/stacks/my-app",
  "composePath": "/data/stacks/my-app/compose.yaml",
  "envPath": "/data/stacks/my-app/.env",
  "suggestedEnvPath": "/data/stacks/my-app/.env"
}

Relocating Stack Files

To move stack files to a new location:

await fetch('/api/stacks/my-app/compose?env=1', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    content: composeContent,
    composePath: '/new/location/compose.yaml',
    envPath: '/new/location/.env',
    moveFromDir: '/old/location',
    restart: false
  })
});

Error Responses

400 Bad Request

• Compose file content is missing
• Invalid YAML syntax
• Invalid file paths

403 Forbidden

• User lacks stacks:edit permission
• User cannot access the specified environment

404 Not Found

• Stack does not exist
• Compose file not found

500 Internal Server Error

• Docker daemon error
• File system error
• Deployment failed

Permissions

Requires stacks:edit permission for the specified environment.