Container Deployment & Commands

Overview

Deploy a saved Stack revision, then check what the target device actually reports. The Console walkthrough uses nginx (v1) on ARK-2252-cc827fdd1713, including runtime commands. The API and maintenance examples use the separate factory-monitor example from Container Stack Management. A retained Smart Intersection screenshot illustrates an independent Error case.

• Deployment selects the Stack revision a WEDA Node should run. The Node pulls its images, starts the containers and reports status to WEDA Cloud.
• Container commands control an already-deployed Stack, such as stopping it for maintenance or restarting its containers. They do not create a new Revision or select a different application image.

Deploy a Stack Revision

Before deploying, check the following:

• Stack: Retain its stackConfigId and the stackRevisionId you intend to deploy.
• Devices: Targets are WEDA Nodes, are Activated and belong to the same Org as the Stack. Use Connected devices for this walkthrough so you can check their results.
• Images: Confirm image tags, device compatibility, registry access and network connectivity from the device to the registry.

In WEDA Console

1. Select the intended Org and open Container Stacks.
2. Find the revision to deploy, nginx (v1) in this example, and select its Deploy action.
3. Select the target devices. The pictured example selects ARK-2252-cc827fdd1713, which is Activated and Connected. Confirm the Stack and version in the heading before submitting.

The heading identifies nginx v1. Select the devices that should run this revision.

4. Select Submit, then Deploy in the confirmation dialog.

Select Deploy to submit the request.

You can also begin from Devices, open a device's Container Stacks tab and select Deploy. In that view, the device is already selected; choose the Stack and its version.

Check the result: Find the deployment for each target device and check its reported status. Submitting the deployment is not proof that the application's containers are running.

Through the API

Use Deploy a Stack Revision to Devices in the operation table below. Its path identifies the Org, Stack and exact revision; supply the target WEDA Node IDs in deviceIds, replacing the example ID with your own:

POST /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions/{stackRevisionId}:deploy

{
  "deviceIds": ["74fe488d5d54"]
}

One call supports 1-128 device IDs. If deployment fails for any device, the whole request fails and returns an error; correct it and resubmit. The 200 response contains deployment records and a per-device deviceActions result:

Action	Meaning
add	The device did not have this Stack deployed.
update	The device had a different revision of the same Stack.
skip	The same revision was already deployed.

Retain the returned deployment identifiers and check each target's reported result. An add or update action does not mean the device has finished applying the revision.

Check Deployment and Runtime Status

Use List Stack Deployments in an Organization to find the intended devices and revisions, or List Stacks Deployed on a Device to focus on one device. To inspect just this Stack, include its stackConfigId:

GET /api/v1/devices/{deviceId}/docker/stacks?stackConfigId={stackConfigId}

Check these fields together:

• Identity: deviceId, stackConfigId and stackRevisionId match the target and revision you selected.
• Deployment status: status describes the Stack's reported lifecycle state.
• Container state: containers[].state describes each container. A Stack can report running while only some containers are running.
• Failure detail: Read deployment reason and each container's error.code, error.message and available error.details.

These are the device's last reported states. Check device connectivity before treating them as a current operational result, and verify the application through its own output or service interface.

The selected revision is Deploying. This intermediate state does not establish application readiness.

The nginx deployment reports Running. Open http://DEVICE_IP:8080, using the target device's reachable IP address, to check the web service itself.

The nginx example returns its default welcome page. This application check complements the device-reported Running status.

Separate failure example: Smart Intersection Analytics reports Error on this device. This screenshot is not a later state of the nginx deployment.

These screenshots show Stack-level status. The Error badge alone does not identify a registry, Compose or application failure; use the diagnostic fields above and the application's logs.

Deployment States

State	How to interpret it
unknown	The status could not be determined.
pending	The desired configuration is queued and deployment has not started.
deploying	The Node is validating Compose, pulling images or starting containers.
awaitingDeployedStatus	Services have been started and the Node is waiting for runtime confirmation.
running	At least one container is running. Check the other containers too.
deployed	The Stack's declared services have started successfully.
completed	A one-shot Stack finished successfully.
exited	Containers have exited. Check their errors to distinguish completion from failure.
paused	The Stack's containers are paused.
stopped	The Stack's containers are stopped but still exist on the device.
removing	Stack removal is in progress.
awaitingRemovedStatus	Removal has run and the Node is waiting for confirmation.
awaitingCleanup	The Node is cleaning up after removal.
retry	A deployment phase is being retried. Inspect the reported reason if this persists.
error	Deployment or runtime management failed. Read the reason and container errors.

Deployment responses use createdAt in v1.2.0. List queries accept sorting=createdAt asc or createdAt desc, with newest first by default. Use skipCount and maxResultCount for pagination.

Run Container Commands

Use commands for runtime changes; use a deployment when you want to apply another Stack revision. The Console example below uses the deployed nginx Stack. The API example uses factory-monitor.

Action	Purpose
start	Start stopped containers in the Stack.
stop	Stop the Stack's running containers.
pause	Pause its containers without removing them.
resume	Resume paused containers.
restart	Stop and start the containers again.

In WEDA Console

1. Open Container Stacks, expand nginx (v1) and find the target device's deployment row. Use that row's Actions, rather than the edit action on the saved Stack definition.
2. For a Running deployment, use the stop or pause control as needed. The row's more-actions menu includes Restart and Remove. Remove undeploys the Stack; it is not a stop command.

Runtime actions apply to the selected device deployment. Restart keeps its deployed revision.

3. After an action, refresh the list and check the device-reported state. Available actions depend on the current state. Resume a paused deployment or start a stopped deployment when you want it running again.

The nginx command example reports Paused. Check the state after resuming it.

The stopped nginx example is shown as Exited in Console. Its deployment still exists; Exited alone does not establish successful application completion.

Check the result: The device's reported state matches the requested action. After starting or restarting nginx, confirm Running and check http://DEVICE_IP:8080 again. The captures show runtime states, not the API command-result fields described below.

Through the API

1. Confirm that the target WEDA Node is Connected and the Stack is deployed on it.

2. Call Run a Container Stack Command, choosing an action in the path. Put the Stack's stackConfigId in the request body. Use the ID saved when creating the Stack, not its revision ID. For example, replace this illustrative ID with your own:

   POST /api/v1/devices/{deviceId}/docker/stacks/commands:restart
   
   {
     "stackConfigId": "c8662da3-ac3b-43bf-b141-67c29a09f066"
   }

3. Retain the returned reqSeqId and query the matching command result as described below.

Note: HTTP 200 is not a device execution result

The command POST returns a delivery reply. Its status: 0 means the command was accepted for delivery; a non-zero status reports a delivery failure. Read its message, then use the result query and device-reported runtime state to confirm execution. A successful relay is not a completed container action.

The POST can wait up to 30 seconds for a reply. Configure an HTTP client timeout longer than 30 seconds. If your request times out, check command results and device state before retrying.

Commands are not an offline job queue. If the device is offline or delivery fails, wait for it to reconnect, check its state and issue the command again if still needed.

Check Command Results

Query List Container Stack Command Results using the device and Stack configuration ID:

GET /api/v1/devices/{deviceId}/docker/stacks/commands/results?stackConfigId={stackConfigId}&range=all&skipCount=0&maxResultCount=20

Find the entry with the reqSeqId returned by your command request. range=latest returns only the most recent entry; it can belong to another request if someone issued a command afterward.

Read Phase and Outcome Separately

data.phase	Meaning
pending	The command was sent toward the device, but no device report has been received. Dispatch failure can also leave an entry here.
ack	The device received and validated the command. Execution is not yet confirmed complete.
progress	Reserved for intermediate reports. Do not wait for this phase in v1.2.0.
result	The device reported the command's final outcome.

Read data.status together with the phase:

• 0: Success. For a completed device execution, also require phase: "result"; a pending entry with status: 0 is not a completed command.
• 1: Failure. Read data.error, even if the phase is still pending.

Read Error Details and Timestamps

Field	How to use it
data.error.code	Identifies the failure category, such as serviceUnavailable, offlineDevice or a device-reported execution error.
data.error.message	Carries the diagnostic reason. Use this instead of the generic failure data.message.
data.createdAt	When WEDA Cloud accepted and recorded the command.
data.executedAt	Execution start reported by the device. It can be null until reported, or remain null if omitted by the device.
data.completedAt	Completion time reported by the device, with the same nullable behavior.

In v1.2.0, the execution timestamps describe device activity rather than the time the Cloud accepted the request. Null-check them before displaying dates. Use phase and outcome to judge completion instead of assuming that a missing timestamp means execution is still pending.

Check the result: The matching request reports phase: "result" and status: 0, and the Stack's reported container state matches the intended action. On failure, inspect data.error.code and data.error.message before taking further action.

Command results are retained for up to one hour, not as permanent history. Read or save the result before replacing or removing the target deployment. They are ordered by data.createdAt, newest first by default; use sorting=createdAt asc for oldest first (executedAt is accepted as a legacy alias and selects the same order). Use skipCount and maxResultCount for pagination.

Remove Deployments

Choose the intended scope before sending a deletion request:

Scope	Request
One Stack on one device	DELETE /api/v1/devices/{deviceId}/docker/stacks?stackConfigId={stackConfigId}
All Stacks on one device	DELETE /api/v1/devices/{deviceId}/stacks/deployments

Caution: Omitting stackConfigId removes all Stacks

For DELETE /api/v1/devices/{deviceId}/docker/stacks, omitting stackConfigId targets all deployed Stacks on that device. To remove only one, always supply its valid, non-empty stackConfigId. The reset endpoint also removes all Stacks on the selected device.

A successful 204 No Content acknowledges the removal request. Removal is asynchronous: wait for the device to apply it and confirm that the intended Stack is no longer deployed. Do not infer device completion from a Cloud-side record disappearing alone, especially while the device is offline.

Removing a deployment does not delete the saved Stack definition or registry configuration. Deploy the intended revisions again when you want the applications back. To delete a saved revision or Stack afterward, follow the deployment-association requirements in Container Stack Management.

API Reference

Operation	API
Deploy a Stack Revision to Devices	POST /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions/{stackRevisionId}:deploy
List Stack Deployments in an Organization	GET /api/v1/orgs/{orgId}/stack-configs/deployments
List Stacks Deployed on a Device	GET /api/v1/devices/{deviceId}/docker/stacks
Undeploy Stacks from a Device	DELETE /api/v1/devices/{deviceId}/docker/stacks?stackConfigId={stackConfigId}
Clear All Stacks from a Device	DELETE /api/v1/devices/{deviceId}/stacks/deployments
Run a Container Stack Command	POST /api/v1/devices/{deviceId}/docker/stacks/commands:{action}
List Container Stack Command Results	GET /api/v1/devices/{deviceId}/docker/stacks/commands/results

For v1.2.0 400 parameter-validation responses, read validationItems[].fieldName and validationItems[].detail. Invalid command or deployment parameters are request errors to correct, not a reason to retry unchanged as if the service had failed.

End-to-End Example: Deploy and Update an Application

Use factory-monitor to connect the Registry, Stack, Deployment and Command procedures in one maintenance walkthrough. Keep the same Org and one Activated, Connected WEDA Node throughout. Prepare your own compatible monitoring images tagged 1.0 and 1.1 in the registry; the image names below are illustrative.

1. Configure the registry. Follow Registry Management to create factory-harbor for harbor.company.com, with credentials that can pull your application images.

   Check: Read back the saved registry host and authentication settings. Image pull access is confirmed when the target device deploys the application.

2. Create the initial Stack. Follow Create a Stack to create factory-monitor from the sample Compose file. Set MONITOR_IMAGE to harbor.company.com/factory/monitor:1.0 and MONITOR_PORT to 8080.

   Check: Retain the returned stackConfigId and initial stackRevisionId. Read the configuration back and confirm both environment values.

3. Deploy image 1.0. Use Deploy a Stack Revision to deploy that initial revision to your selected WEDA Node.

   Check: Match the device, Stack and revision IDs in the deployment result. Confirm the monitor container is running and the application's service responds as expected.

4. Stop the application for maintenance. Use Run a Container Stack Command, selecting stop in the request path and supplying the same stackConfigId in the body. Retain its reqSeqId and use Check Command Results to follow that request.

   Check: Wait for the matching result to report phase: "result" and status: 0, then confirm the container is stopped. The Stack remains deployed and still references the initial revision.

5. Save a revision for image 1.1. Follow Update and Compare Revisions to update the existing Stack. Change MONITOR_IMAGE to harbor.company.com/factory/monitor:1.1 and retain MONITOR_PORT: "8080" in the supplied environment dictionary.

   Check: Keep the new stackRevisionId, compare it with the initial revision and confirm the image change. The stackConfigId stays the same. Saving this revision does not apply it to the device.

6. Deploy the new revision. Deploy again to the same WEDA Node, supplying the new stackRevisionId. Through the API, place it in the Deploy a Stack Revision to Devices path. Wait for the device to apply the configuration and start the updated application.

   Check: Confirm the reported deployment identifies the new revision, the container is running and the application behaves as expected with image 1.1.

7. Restart the updated application (optional maintenance check). Use Run a Container Stack Command, selecting restart in the request path and supplying the same stackConfigId in the body. Follow its own reqSeqId to completion.

   Check: Confirm a successful final command result and that the container is running again. Its deployed stackRevisionId remains the new revision selected in step 6.

The stop and restart steps demonstrate runtime maintenance. Applying a new revision requires Deploy a Stack Revision to Devices; a restart operates on the currently deployed revision and is not required to finish the upgrade.

Related

• Prepare and select revisions in Container Stack Management.
• Configure private image access in Registry Management.
• Use Tunnel Management when troubleshooting requires access to a service running on the device.