Container Deployment & Commands
Overview
Container Deployment pushes a specific Container Stack revision to one or more WEDA Nodes. WEDA Node handles image pulling, signature verification, and container lifecycle on the edge device. Deployment status is synchronized back to WEDA Core — updates are visible within approximately one minute.
Container Commands let you control the runtime state of already-deployed stacks without redeploying — useful for pausing a workload during maintenance or restarting after a configuration change.
Deployment Flow
Deployment States
The deployment API reports the following aggregate states for each Stack on a device:
| State | Description |
|---|---|
unknown | The deployment status could not be determined |
pending | The desired Stack revision is queued but deployment has not started |
deploying | WEDA Node is validating the Compose configuration, pulling images, or starting containers |
awaitingDeployedStatus | Compose has started the services and WEDA Node is waiting to confirm their runtime status |
running | At least one container in the Stack is running |
deployed | All services declared by the Stack have started successfully |
completed | A one-shot Stack finished successfully |
exited | All containers in the Stack have exited. Inspect containers[].error and reason for details |
paused | All containers in the Stack are paused |
stopped | All containers in the Stack are stopped but still exist on the device |
removing | WEDA Node is running Compose down to remove the Stack |
awaitingRemovedStatus | Compose down has completed and WEDA Node is confirming removal |
awaitingCleanup | The Stack was removed and WEDA Node is cleaning up local files and bookkeeping |
retry | A deployment phase failed temporarily and has been scheduled for retry |
error | Deployment or a runtime operation failed. Inspect reason and container errors for details |
WEDA Node internally downloads and verifies the signed Stack package, validates the
Compose configuration, pulls images, and starts containers. These internal phases are
represented by the public deploying status rather than separate API status values.
Each entry in containers[] reports its own state and, when it failed, an error object with code, message, a timestamp (ISO 8601), and details:
{
"status": "exited",
"containers": [
{
"id": "66edbb7e-24b1-4622-bbe2-9f63cfef5565",
"name": "edge_weda-application-1",
"state": "exited",
"error": {
"code": "OOMKilled",
"message": "Exited (137) 4 seconds ago",
"timestamp": "2026-04-30T09:05:46Z"
}
}
]
}
Operations
Deployment
| Operation | API | Description |
|---|---|---|
| Deploy Stack | POST /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions/{stackRevisionId}:deploy | Deploy a specific revision to one or more WEDA Nodes |
| List Deployments (Org) | GET /api/v1/orgs/{orgId}/stack-configs/deployments | List all stack deployments across devices in an Org |
| List Stacks on Device | GET /api/v1/devices/{deviceId}/docker/stacks | List Docker stacks currently deployed on a specific device |
| Undeploy a Stack | DELETE /api/v1/devices/{deviceId}/docker/stacks?stackConfigId={stackConfigId} | Remove one specified Stack while preserving other Stacks on the device |
| Undeploy All Stacks | DELETE /api/v1/devices/{deviceId}/docker/stacks | Remove all active Stack deployments from a device |
| Clear All Deployments | DELETE /api/v1/devices/{deviceId}/stacks/deployments | Reset the device to an empty Stack configuration and delete all deployment records |
DELETE /api/v1/devices/{deviceId}/stacks/deployments stops and removes every container stack on the device and permanently deletes all deployment records. Use only when intentionally resetting a device to a clean state.
Stack removal is asynchronous. A successful API response acknowledges the removal request but does not guarantee that WEDA Node has already removed every container. Check the device's deployment and container status to confirm completion.
Container Commands
| Operation | API | Description |
|---|---|---|
| Execute Command | POST /api/v1/devices/{deviceId}/docker/stacks/commands:{action} | Execute a runtime command on a deployed stack |
| Get Command Results | GET /api/v1/devices/{deviceId}/docker/stacks/commands/results | Retrieve results of previously executed commands |
Available {action} values: start, stop, pause, resume, restart
Both operations require stackConfigId to identify which deployed stack they target. Execute Command
takes it in the request body; Get Command Results takes it as a query parameter.
Get Command Results also accepts range to narrow the result set: all (default) returns every
recorded command, latest returns only the most recent one. Use latest to check the outcome of a
command you just issued.
Constraints
Deployment
- Target devices must be activated. An activated device may be online or offline when the deploy request is issued
- If an activated device is offline, the desired Stack configuration remains queued and is applied after the device reconnects
- A single deploy call supports up to 128 device IDs
- Target devices and the Stack Config must belong to the same Org
- WEDA Core returns a per-device action for each target:
add(new),update(revision upgrade), orskip(same revision already deployed)
Container Commands
- Commands are volatile — unlike Stack deployment (which is queued and applied once the device reconnects), a command is not retried or queued if the device is offline
- If the device is offline when a command is issued, the API still returns
200 OK(request accepted), but the command is discarded before reaching the device — it will not be delivered or executed once the device reconnects - Confirm the device is online before issuing a command that must take effect, or check the device's status via List Stacks on Device beforehand
- Use command results to verify whether WEDA Node executed the requested action successfully
- Command results are cached for 1 hour; results older than 1 hour cannot be retrieved
Scenario
A system integrator deploys a monitoring stack to all devices on a factory line, then restarts it after updating a configuration file:
Related
- Prepare the Docker Compose application definition before deploying: Container Stack Management
- Set up private registry credentials for image pulls: Registry Management
- Access a device terminal during deployment troubleshooting: Remote Access — Tunnel