Docker Swarm

​

Get Swarm Nodes

curl -X GET "https://your-dokploy-instance.com/api/swarm.getNodes?serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Query Parameters

​

Response

• Node ID and hostname
• Role (manager or worker)
• Availability status
• Node state and version
• Resource information (CPU, memory)
• Labels and platform details

[
  {
    "ID": "node_abc123",
    "Version": {
      "Index": 42
    },
    "CreatedAt": "2024-01-15T10:30:00.000Z",
    "UpdatedAt": "2024-01-15T12:00:00.000Z",
    "Spec": {
      "Name": "manager-1",
      "Role": "manager",
      "Availability": "active"
    },
    "Description": {
      "Hostname": "manager-1",
      "Platform": {
        "Architecture": "x86_64",
        "OS": "linux"
      },
      "Resources": {
        "NanoCPUs": 4000000000,
        "MemoryBytes": 8589934592
      }
    },
    "Status": {
      "State": "ready",
      "Addr": "192.168.1.10"
    },
    "ManagerStatus": {
      "Leader": true,
      "Reachability": "reachable",
      "Addr": "192.168.1.10:2377"
    }
  }
]

​

Get Node Information

curl -X GET "https://your-dokploy-instance.com/api/swarm.getNodeInfo?nodeId=node_abc123&serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Query Parameters

​

Response

• Full node specification
• Current status and state
• Manager status (if applicable)
• Resource allocation
• Platform and engine details
• Labels and constraints

​

Get Node Applications

curl -X GET "https://your-dokploy-instance.com/api/swarm.getNodeApps?serverId=server_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Query Parameters

​

Response

• Service names and IDs
• Replica counts and status
• Node placement
• Network configuration
• Resource allocation

​

Understanding Docker Swarm in Dokploy

​

High Availability

• Multiple manager nodes for fault tolerance
• Automatic leader election
• Service health monitoring and automatic recovery

​

Load Balancing

• Built-in ingress load balancing
• Service discovery across the cluster
• Automatic request routing

​

Scaling

• Easy horizontal scaling of services
• Rolling updates with zero downtime
• Resource constraints and reservations

​

Security

• Mutual TLS authentication between nodes
• Encrypted control plane communication
• Secret management for sensitive data

​

Node Roles

• Orchestrate and manage the cluster
• Maintain cluster state
• Schedule services
• Should have odd number (3, 5, 7) for quorum

• Execute container workloads
• Receive tasks from managers
• Report status back to managers

​

Common Swarm Operations

​

Checking Cluster Health

1. List all nodes to verify cluster membership
2. Check node info for each manager to ensure reachability
3. Review applications to confirm services are running

​

Service Distribution

• Node availability and state
• Resource requirements
• Placement constraints
• Spread preferences

​

Best Practices

​

Error Handling

​

Common Error Responses

{
  "error": "Node not found",
  "message": "The specified node ID does not exist in the swarm"
}

{
  "error": "Swarm not available",
  "message": "This node is not part of a swarm. Initialize or join a swarm first."
}

{
  "error": "Unauthorized",
  "message": "You don't have permission to access this server's swarm"
}