Skip to main content
PUT
/
api
/
stacks
/
{name}
/
compose
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
  }'

{
  "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
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
  }'

{
  "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.

Build docs developers (and LLMs) love

Get started for freeTalk to us