Skip to content

API Deployment Examples

Jump to bottom
DockMon Bot edited this page Dec 24, 2025 · 2 revisions

API Deployment Examples

Comprehensive examples for deploying containers and stacks via the DockMon REST API.

See API Access for authentication setup and basic API usage.

Quick Reference

Endpoint Method Purpose
/api/deployments POST Create a deployment (planning state)
/api/deployments/{id}/execute POST Execute a deployment
/api/deployments/{id} GET Get deployment status
/api/deployments GET List all deployments
/api/deployments/{id} DELETE Delete a deployment

Understanding Deployments

Two-step process:

  1. Create deployment → Status: planning (validates but doesn't deploy)
  2. Execute deployment → Status: executing → running (deploys containers)

Why two steps?

  • Review deployment before execution
  • Catch validation errors early
  • Support scheduled deployments (future feature)

Stack Deployments (Docker Compose)

Basic Stack Example

Deploy a simple nginx + redis stack:

Step 1: Create deployment

curl -X POST https://dockmon.local:8001/api/deployments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "host_id": "your-host-id-here",
    "name": "nginx-redis-stack",
    "deployment_type": "stack",
    "definition": {
      "compose_yaml": "services:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"8080:80\"\n  cache:\n    image: redis:alpine"
    },
    "rollback_on_failure": true
  }'

Step 2: Execute deployment

# Use deployment ID from create response
curl -X POST https://dockmon.local:8001/api/deployments/DEPLOYMENT_ID/execute \
  -H "Authorization: Bearer YOUR_API_KEY"

Stack with Variables

Use variables for flexible deployments:

{
  "host_id": "your-host-id",
  "name": "webapp-stack",
  "deployment_type": "stack",
  "definition": {
    "compose_yaml": "services:\n  app:\n    image: ${APP_IMAGE}\n    ports:\n      - \"${APP_PORT}:8080\"\n    environment:\n      - DB_HOST=${DB_HOST}",
    "variables": {
      "APP_IMAGE": "myapp:1.0",
      "APP_PORT": "3000",
      "DB_HOST": "postgres.local"
    }
  }
}

Real-World Stack Example: Media Server

Complete Plex + Tautulli stack with GPU transcoding:

{
  "host_id": "your-host-id",
  "name": "media-server",
  "deployment_type": "stack",
  "definition": {
    "compose_yaml": "services:\n  plex:\n    image: plexinc/pms-docker:latest\n    container_name: plex\n    network_mode: host\n    devices:\n      - /dev/dri:/dev/dri:rwm\n    environment:\n      - PLEX_UID=1000\n      - PLEX_GID=1000\n      - TZ=America/New_York\n    volumes:\n      - /data/plex:/config\n      - /data/media:/media\n\n  tautulli:\n    image: ghcr.io/tautulli/tautulli:latest\n    container_name: tautulli\n    ports:\n      - \"8181:8181\"\n    environment:\n      - TZ=America/New_York\n    volumes:\n      - /data/tautulli:/config"
  }
}

Note: Use \n for newlines in the compose_yaml string (JSON requirement).

VPN + Application Stack

Gluetun VPN with qBittorrent using network sharing:

{
  "host_id": "your-host-id",
  "name": "vpn-torrent",
  "deployment_type": "stack",
  "definition": {
    "compose_yaml": "services:\n  gluetun:\n    image: qmcgaw/gluetun:latest\n    container_name: gluetun\n    cap_add:\n      - NET_ADMIN\n    environment:\n      - VPN_SERVICE_PROVIDER=protonvpn\n      - OPENVPN_USER=${VPN_USER}\n      - OPENVPN_PASSWORD=${VPN_PASS}\n    ports:\n      - \"8080:8080\"\n\n  qbittorrent:\n    image: linuxserver/qbittorrent:latest\n    container_name: qbittorrent\n    network_mode: \"service:gluetun\"\n    environment:\n      - PUID=1000\n      - PGID=1000\n    volumes:\n      - /data/qbittorrent:/config\n      - /data/downloads:/downloads",
    "variables": {
      "VPN_USER": "your-vpn-username",
      "VPN_PASS": "your-vpn-password"
    }
  }
}

Docker Compose Features Supported (v2.1.8+)

DockMon supports these Docker Compose directives:

network_mode

services:
  vpn:
    image: qmcgaw/gluetun
    network_mode: host  # or: bridge, none, container:other_container

JSON format:

{
  "compose_yaml": "services:\n  vpn:\n    image: qmcgaw/gluetun\n    network_mode: host"
}

devices (Hardware Access)

services:
  plex:
    image: plexinc/pms-docker
    devices:
      - /dev/dri:/dev/dri:rwm  # GPU for transcoding

JSON format:

{
  "compose_yaml": "services:\n  plex:\n    image: plexinc/pms-docker\n    devices:\n      - /dev/dri:/dev/dri:rwm"
}

extra_hosts (Custom DNS)

services:
  app:
    image: myapp
    extra_hosts:
      - "db.local:192.168.1.100"
      - "api.local:192.168.1.200"

JSON format:

{
  "compose_yaml": "services:\n  app:\n    image: myapp\n    extra_hosts:\n      - db.local:192.168.1.100\n      - api.local:192.168.1.200"
}

cap_add / cap_drop (Linux Capabilities)

services:
  vpn:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN  # Required for VPN

JSON format:

{
  "compose_yaml": "services:\n  vpn:\n    image: qmcgaw/gluetun\n    cap_add:\n      - NET_ADMIN"
}

Getting Host IDs

You need a host ID to deploy. Get the list:

curl https://dockmon.local:8001/api/hosts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  {
    "id": "86a10392-2289-409f-899d-5f5c799086da",
    "name": "Local Docker",
    "url": "unix:///var/run/docker.sock",
    "status": "online"
  }
]

Use the id field in your deployment requests.

Checking Deployment Status

Get Specific Deployment

curl https://dockmon.local:8001/api/deployments/DEPLOYMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "86a10392-...:c7d9d8f1b890",
  "name": "nginx-redis-stack",
  "status": "running",
  "progress_percent": 100,
  "error_message": null,
  "container_ids": ["a1b2c3d4e5f6", "f6e5d4c3b2a1"]
}

List All Deployments

curl https://dockmon.local:8001/api/deployments \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

Validation Errors

If your compose file has errors:

Request:

{
  "definition": {
    "compose_yaml": "services:\n  invalid:\n    network_mode: host\n    networks:\n      - mynetwork"
  }
}

Response (400 Bad Request):

{
  "detail": "Compose validation failed: Service 'invalid': Cannot use both 'network_mode' and 'networks'. These options are mutually exclusive."
}

Common Errors

Error Cause Fix
Missing required field: services Invalid compose YAML Ensure compose_yaml has services: section
Cannot use both 'network_mode' and 'networks' Conflicting directives Remove either network_mode or networks
Stack deployment requires 'compose_yaml' Missing field Add compose_yaml to definition
Invalid port mapping Bad port format Use format: "8080:80" or "127.0.0.1:8080:80"

Postman Collection

Import into Postman

  1. Create new request collection
  2. Add Authorization header to collection:
    • Key: Authorization
    • Value: Bearer YOUR_API_KEY
  3. Set base URL: https://dockmon.local:8001
  4. Disable SSL verification (Settings → SSL certificate verification → OFF)

Example Requests

Create Stack:

  • Method: POST
  • URL: {{base_url}}/api/deployments
  • Body: See examples above (select "raw" + "JSON")

Execute:

  • Method: POST
  • URL: {{base_url}}/api/deployments/{{deployment_id}}/execute
  • Body: (none)

Get Status:

  • Method: GET
  • URL: {{base_url}}/api/deployments/{{deployment_id}}

Python Script Example

Complete Python script for deploying stacks:

import requests
import time

API_KEY = "dockmon_your_api_key_here"
BASE_URL = "https://dockmon.local:8001"
HOST_ID = "your-host-id"

# Disable SSL warnings (for self-signed certs)
import urllib3
urllib3.disable_warnings()

def deploy_stack(name, compose_yaml, variables=None):
    """Deploy a Docker Compose stack via DockMon API"""

    # Step 1: Create deployment
    create_response = requests.post(
        f"{BASE_URL}/api/deployments",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "host_id": HOST_ID,
            "name": name,
            "deployment_type": "stack",
            "definition": {
                "compose_yaml": compose_yaml,
                "variables": variables or {}
            },
            "rollback_on_failure": True
        },
        verify=False
    )

    if create_response.status_code != 201:
        print(f"Failed to create deployment: {create_response.text}")
        return None

    deployment = create_response.json()
    deployment_id = deployment["id"]
    print(f"Created deployment: {deployment_id}")

    # Step 2: Execute deployment
    execute_response = requests.post(
        f"{BASE_URL}/api/deployments/{deployment_id}/execute",
        headers={"Authorization": f"Bearer {API_KEY}"},
        verify=False
    )

    if execute_response.status_code != 200:
        print(f"Failed to execute: {execute_response.text}")
        return None

    print(f"Executing deployment...")

    # Step 3: Wait for completion
    while True:
        status_response = requests.get(
            f"{BASE_URL}/api/deployments/{deployment_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            verify=False
        )

        status = status_response.json()
        state = status["status"]
        progress = status["progress_percent"]

        print(f"Status: {state} ({progress}%)")

        if state == "running":
            print("✓ Deployment successful!")
            return deployment_id
        elif state in ["failed", "rolled_back"]:
            print(f"✗ Deployment failed: {status.get('error_message')}")
            return None

        time.sleep(2)

# Example usage
compose_yaml = """services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  cache:
    image: redis:alpine
"""

deployment_id = deploy_stack("my-stack", compose_yaml)

Troubleshooting

SSL Certificate Errors

If you see SSL errors:

curl:

curl -k https://dockmon.local:8001/api/hosts ...
# -k flag skips SSL verification

Python:

requests.get(url, verify=False)

Production: Use proper SSL certificates or add DockMon's CA to your system trust store.

JSON Formatting

Common mistake: Breaking compose_yaml across multiple lines

❌ Wrong:

{
  "compose_yaml": "services:
    web:
      image: nginx"
}

✓ Correct:

{
  "compose_yaml": "services:\n  web:\n    image: nginx"
}

Use \n for newlines, keep the string on one line.

Next Steps

API Reference

Full API documentation available at: https://dockmon.local:8001/docs

Interactive Swagger UI with:

  • Complete endpoint list
  • Request/response schemas
  • Try-it-now functionality

Getting Started

User Guide

Configuration

Remote Monitoring

Access Control

Advanced

Development

Help

Clone this wiki locally