Container Stack Management

Overview

A Container Stack is a Docker Compose-based application definition stored in WEDA Core. Create a Stack from a Compose file, then save changes as new revisions so you can choose which configuration to deploy to your WEDA Nodes.

Revisions let you compare changes, deploy different configurations to different devices, or select an older configuration for deployment.

Field	What it identifies
stackConfigId	The Stack across its revisions. Keep this ID when updating the same application definition.
stackRevisionId	One saved revision. Use this ID when reading, comparing or deploying a particular revision.
version	The revision's version number. Use the returned value for display; an API requesting a revision ID needs stackRevisionId.

Note: A saved revision is separate from a deployment

Updating a Stack creates a new revision. Devices continue using their deployed revision until you explicitly deploy another one. Saving a new revision does not update a running application.

Create a Stack

The Console example uses a single-service nginx Stack. The API example below uses a separate factory-monitor application to demonstrate environment variables and revision comparison.

In WEDA Console

Open the sample docker-compose.yml, or download docker-compose.yml. It runs nginx:1.27-alpine as service web, publishing host port 8080 to container port 80. This file needs no environment values or prepared host files. Check that port 8080 is available before deploying it.

1. Select the Org containing the target devices and registry configuration.
2. Open Container Stacks.

Use Add to create the application definition in the selected Org.

3. Select Add and complete Basic information:
   • Stack name: nginx.
   • Type: Compose.
   • Description: nginx-example in this example. This field is optional.
   • Docker compose file: Upload the downloaded docker-compose.yml.

The nginx configuration is ready to save. No Environment variables are required for this sample.

4. Leave Environment variables empty for this nginx file. For a Compose file using ${VARIABLE_NAME}, supply its required values here.
5. Select Submit, then Add in the confirmation dialog.

Select Add to save the application definition.

Check the result: nginx (v1) appears in the selected Org. Check the saved Compose content before deploying it. Saving the Stack is separate from running it on a device.

Through the API

The independent API example uses an existing monitoring application image in the private registry configured in Registry Management, saved as factory-monitor. It assumes that the application listens on container port 8080. Substitute your own image and application settings before deployment; building the image is outside this guide.

Save the following as docker-compose.yaml:

services:
  monitor:
    image: "${MONITOR_IMAGE}"
    ports:
      - "${MONITOR_PORT}:8080"

The two variables select the image and the host port. Prepare these values for the Stack:

Environment key	Initial example value
MONITOR_IMAGE	harbor.company.com/factory/monitor:1.0
MONITOR_PORT	8080

Use Create a Stack Configuration in the operation table below, with type: "compose". Prepare the Compose input according to the interface you use:

Interface	Compose input
WEDA Console	Upload the original docker-compose.yaml file. No manual Base64 conversion is needed.
REST API	Encode the file's UTF-8 text as Base64 and put the resulting string in composeFileContent.

Note: Base64 is required for REST Compose input

Encode the file contents, not the filename or file path. Do not send raw YAML in composeFileContent. This requirement applies to both Create a Stack Configuration and Create a Stack Configuration Revision whenever that field is supplied.

For the exact Compose file shown earlier, the request body is below. When you edit or replace that file, generate a new Base64 value from your own content instead of reusing this sample value.

{
  "stackName": "factory-monitor",
  "type": "compose",
  "composeFileContent": "c2VydmljZXM6CiAgbW9uaXRvcjoKICAgIGltYWdlOiAiJHtNT05JVE9SX0lNQUdFfSIKICAgIHBvcnRzOgogICAgICAtICIke01PTklUT1JfUE9SVH06ODA4MCIK",
  "environment": {
    "MONITOR_IMAGE": "harbor.company.com/factory/monitor:1.0",
    "MONITOR_PORT": "8080"
  },
  "description": "Factory monitoring application, image 1.0"
}

A successful creation returns 201 Created with the saved configuration, stackConfigId, stackRevisionId and version. Keep the actual returned IDs rather than substituting a version number into later API paths.

Update and Compare Revisions

To create a new version in Console:

1. Select the pencil icon for nginx (v1) to open Edit Container Stack. The name and type are read-only.
2. Change Description from nginx-example to nginx-example-v2. Keep the sample Compose content unchanged. The edit screenshot displays the uploaded file as nginx.yml; the filename does not determine the Stack version.
3. Select Submit and confirm the edit if prompted.

Saving the edited definition creates a new version, even when the demonstrated change is its description.

The saved edit appears as v2. The device remains listed under v1; saving v2 has not deployed it.

Check the result: Both nginx (v2) and nginx (v1) are listed. Deploy v2 explicitly when you want the device to use it. This example demonstrates a saved revision, not an nginx image upgrade.

For an API-based image update and comparison, suppose the monitoring image 1.1 is now available in the same registry. Update the existing factory-monitor Stack instead of creating another Stack with the same name; a duplicate name returns 409 Conflict.

1. Read the latest configuration using Get the Latest Stack Configuration Revision. Retain the current stackRevisionId as the comparison source.

2. Send this body to Create a Stack Configuration Revision, using the same orgId and stackConfigId:

   {
     "environment": {
       "MONITOR_IMAGE": "harbor.company.com/factory/monitor:1.1",
       "MONITOR_PORT": "8080"
     },
     "description": "Factory monitoring application, image 1.1"
   }

3. Retain the new stackRevisionId returned by the update. The stackConfigId still identifies the same Stack.

4. Call Compare Stack Configuration Revisions, passing the previous ID as sourceStackRevisionId and the new ID as targetStackRevisionId.

Check the result: Read the new revision and confirm that MONITOR_IMAGE now selects image 1.1, while MONITOR_PORT remains 8080. Review environmentDiff, fieldDifferences and yamlDiff in the comparison response. This update changes the environment and description; the Compose text remains unchanged.

Note: PATCH fields and environment replacement

The Create a Stack Configuration Revision API accepts composeFileContent, environment and description. Omitted fields and fields explicitly set to null retain their current values. A supplied environment object replaces the saved environment dictionary, so include the keys you want to retain, as the example does with MONITOR_PORT. If you change the Compose file itself, encode the updated contents as Base64 before supplying composeFileContent.

When ready, deploy the selected revision through Container Deployment & Commands. To return a device to an older configuration, select that older revision for deployment; saving or reading it alone does not change the device.

Operations

Stack Configuration

Operation	API	Description
Create a Stack Configuration	POST /api/v1/orgs/{orgId}/stack-configs	Create a Stack and its initial revision.
List Stack Configurations	GET /api/v1/orgs/{orgId}/stack-configs	List Stack configurations in an Org.
Get the Latest Stack Configuration Revision	GET /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}	Read the Stack's latest revision.
Create a Stack Configuration Revision	PATCH /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}	Save changes as a new revision.
Delete a Stack Configuration	DELETE /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}	Delete the Stack and its revisions, subject to deployment checks.

Revision Management

Operation	API	Description
List Stack Configuration Revisions	GET /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions	List saved revisions for one Stack.
Get a Stack Configuration Revision	GET /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions/{stackRevisionId}	Read a specific revision.
Compare Stack Configuration Revisions	GET /api/v1/orgs/{orgId}/stack-configs/revisions/diff?sourceStackRevisionId={sourceId}&targetStackRevisionId={targetId}	Compare two saved revisions in the Org.
Delete a Stack Configuration Revision	DELETE /api/v1/orgs/{orgId}/stack-configs/{stackConfigId}/revisions/{stackRevisionId}	Delete one revision, subject to deployment checks.

Constraints

• Stack name: Required and unique within the Org, with at most 63 characters. Use lowercase letters, digits and hyphens. Start and end with a letter or digit; consecutive hyphens are not accepted. A duplicate name returns 409 Conflict.
• Type: Use compose for Docker Compose definitions.
• Compose content: For REST requests, provide Base64-encoded valid Compose YAML. Use the file upload in WEDA Console.
• Environment: Optional key/value settings referenced in Compose using ${VARIABLE_NAME}. Prepare the required values before deployment.
• Description: Optional text describing the saved configuration.
• Revision identity: Supply orgId, stackConfigId and stackRevisionId together when reading a specific revision. A revision from a different Stack or Org does not match that path.

For example, factory-monitor-01 is a valid name. Factory_Monitor, factory--monitor and -factory-monitor are invalid.

Timestamps and List Queries in v1.2.0

• Read createdAt, an ISO 8601 timestamp, from Stack and revision responses. Update clients that previously read creationTime.
• Stack lists support createdAt and stackName sorting; revision lists support createdAt. Use asc or desc, such as sorting=createdAt desc. Newest first is the default.
• Use skipCount and maxResultCount for pagination. The page size is 1-1000.
• Use Get the Latest Stack Configuration Revision when you need the latest revision of one Stack, or Get a Stack Configuration Revision when you need an exact saved revision.

For 400 field-validation errors, inspect validationItems[].fieldName and validationItems[].detail. Correct the indicated field rather than retrying the same request unchanged.

Delete a Revision or Stack

Deployment associations must be removed before deleting the configuration they reference:

• Delete Revision: Remove deployments associated with that specific revision first.
• Delete Stack: Check the deployments associated with its revisions before deleting the whole Stack.

Caution: Stopping containers is not undeploying a Stack

A stop command changes runtime state; it does not remove the Deployment association checked by configuration deletion. Use the removal procedure in Container Deployment & Commands before deleting a deployed revision or Stack.

A successful deletion returns 204 No Content. Read the Stack or revision list afterward to confirm removal.

Related

• Configure access to private images in Registry Management.
• Deploy a selected revision and manage its runtime in Container Deployment & Commands.