Deploy Stack

Create and deploy a new compose stack

POST /api/stacks

cURL

curl -X POST "https://your-dockhand-instance.com/api/stacks?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_token" \
  -d '{
    "name": "my-app",
    "compose": "version: '\''3.8'\''\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"8080:80\"\n    environment:\n      - APP_ENV=${APP_ENV}",
    "start": true,
    "envVars": [
      {
        "key": "APP_ENV",
        "value": "production",
        "isSecret": false
      },
      {
        "key": "API_KEY",
        "value": "secret_key_here",
        "isSecret": true
      }
    ]
  }'

Success

{
  "success": true,
  "started": true,
  "output": "[+] Running 2/2\n ✔ Network my-app_default  Created\n ✔ Container my-app-web-1  Started"
}

Query Parameters

env · string · required

Environment ID where the stack will be deployed

Body Parameters

name · string · required

Stack name (must be unique within the environment)

compose · string · required

Docker Compose file content (YAML)

start · boolean · default: true

Whether to start the stack immediately. If false, only creates the compose file without deploying.

envVars · array

Environment variables for the stack

Show Environment Variable Object

key · string · required

Variable name

value · string · required

Variable value

isSecret · boolean · default: false

Whether this is a secret (stored in database, not in .env file)

rawEnvContent · string

Raw .env file content (non-secrets with comments preserved)

composePath · string

Custom path for the compose file (for adopted stacks)

envPath · string

Custom path for the .env file (for adopted stacks)

Response

This endpoint uses Server-Sent Events (SSE) to stream deployment progress.

success · boolean

Whether the deployment succeeded

started · boolean

Whether the stack was started (always true if start was true)

output · string

Docker Compose output from the deployment

error · string

Error message if deployment failed

Behavior

• If start=false, only creates the compose and env files without running docker compose up
• Secrets (variables with isSecret=true) are stored in the database and injected at runtime
• Non-secret variables are written to the .env file
• The stack is marked as internal source type in the database
• Deployment uses SSE to keep the connection alive during long operations

cURL

curl -X POST "https://your-dockhand-instance.com/api/stacks?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_token" \
  -d '{
    "name": "my-app",
    "compose": "version: '\''3.8'\''\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"8080:80\"\n    environment:\n      - APP_ENV=${APP_ENV}",
    "start": true,
    "envVars": [
      {
        "key": "APP_ENV",
        "value": "production",
        "isSecret": false
      },
      {
        "key": "API_KEY",
        "value": "secret_key_here",
        "isSecret": true
      }
    ]
  }'

Success

{
  "success": true,
  "started": true,
  "output": "[+] Running 2/2\n ✔ Network my-app_default  Created\n ✔ Container my-app-web-1  Started"
}

Compose File Example

compose.yaml

version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    environment:
      - NGINX_HOST=${DOMAIN}
      - NGINX_PORT=80
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

  app:
    image: node:18-alpine
    working_dir: /app
    volumes:
      - ./app:/app
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - API_KEY=${API_KEY}
    command: npm start
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=${DB_NAME}
    volumes:
      - db-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  db-data:

networks:
  default:
    name: my-app-network

Error Responses

400 Bad Request

• Stack name is missing or invalid
• Compose file content is missing or invalid
• Invalid YAML syntax

403 Forbidden

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

500 Internal Server Error

• Docker daemon error
• File system error
• Database error

Permissions

Requires stacks:create permission for the specified environment.