Docker — container/stop

When to Use

Cleanup before removal: Stop a running container before calling container/remove — running containers cannot be removed without force.
Blue-green cutover: After verifying the new (blue) container is healthy, stop the old (green) container to complete the traffic switch.
Maintenance window: Gracefully stop containers before applying host-level updates or reboots, allowing applications to flush buffers and close connections.
Resource conservation: Stop idle containers during low-traffic periods (e.g. nights and weekends) to free CPU and memory on shared infrastructure.
Failed deployment rollback: Stop the newly deployed container that is failing health checks before restarting the previous version.

Docker sends SIGTERM first and gives the container's process up to 10 seconds (default) to exit gracefully. After the timeout, SIGKILL is sent. Applications that need longer shutdown windows (e.g. draining active HTTP connections) should set a longer timeoutSeconds value.

Configuration

Connection Fields

Field	Type	Default	Description
`dockerHost`	string	`unix:///var/run/docker.sock`	Docker socket path or TCP endpoint
`connectionType`	string	`unixsocket`	`unixsocket` \| `tcp` \| `tcptls`
`tlsCertPath`	string	—	TLS certificate directory. Required for `tcptls`. optional
`timeoutSeconds`	int	30	Grace period before SIGKILL. Increase for applications with long shutdown sequences. optional

Operation Fields

Field	Type	Required	Description
`resource`	string	required	Must be `container`
`operation`	string	required	Must be `stop`
`ContainerId`	string	required	Container ID (full or short) or container name

Sample Configuration

{
  "resource": "container",
  "operation": "stop",
  "ContainerId": "api-service-green",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket",
    "timeoutSeconds": 30
  }
}

Validation Errors

Error Code	Trigger	Resolution
`MISSING_INPUT`	`ContainerId` is empty	Provide the container name or ID.
`NOT_FOUND`	Container does not exist	Container may already have been removed. Handle NOT_FOUND as non-fatal in cleanup workflows.
`DOCKER_API_ERROR`	Daemon error during stop	Check daemon logs. Very rare — typically a container with a corrupted state.

Output

Success Port

Field	Type	Description
`containerId`	string	ID of the container that was stopped
`status`	string	`success`
`resource`	string	`container`
`operation`	string	`stop`

Error Port

On failure, the error port receives errorCode, message, resource, and operation. NOT_FOUND should be treated as acceptable in cleanup and rollback workflows where the container may or may not be running.

Sample Output

{
  "containerId": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
  "status": "success",
  "resource": "container",
  "operation": "stop"
}

Expression Reference

Expression	Returns
`{{ $output.containerId }}`	ID of the stopped container — pass to `container/remove` downstream
`{{ $output.status }}`	`success` when stop completed

Node Policies & GuardRails

Policy	Detail
Stop before remove	`container/remove` will fail with `CONFLICT` on a running container. Always place `container/stop` before `container/remove` in cleanup workflows.
Adjust timeout for graceful apps	Applications that handle SIGTERM for connection draining need a longer timeout. Default is 10 seconds Docker-side; set `timeoutSeconds` in node config to accommodate your application's shutdown sequence.
No remote TCP without TLS	Use `tcptls` for remote hosts.
Handle NOT_FOUND gracefully	In cleanup and rollback pipelines, a missing container is an acceptable outcome. Route `NOT_FOUND` to a no-op branch rather than an alert.
Always wire the error port	Daemon downtime will cause stop to fail. The error port must be connected to a fallback handler.

Examples

Example 1: Stop-then-remove cleanup

// Node 1: container/stop
{ "resource": "container", "operation": "stop", "ContainerId": "old-job-container" }

// Node 2: container/remove (uses same containerId)
{ "resource": "container", "operation": "remove", "ContainerId": "{{ $nodes.stopContainer.output.containerId }}" }

Example 2: Blue-green cutover — stop green after blue is healthy

// After container/exec health check passes on blue:
{
  "resource": "container",
  "operation": "stop",
  "ContainerId": "api-service-green"
}
// Then remove green:
{ "resource": "container", "operation": "remove", "ContainerId": "api-service-green" }

Example 3: Graceful shutdown for long-lived services

{
  "resource": "container",
  "operation": "stop",
  "ContainerId": "websocket-server",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket",
    "timeoutSeconds": 60
  }
}
// 60-second grace period allows WebSocket connections to drain cleanly