Container Management

Manage Docker containers, images, volumes, and networks on remote devices through the Umoo web console.

Overview

The container plugin provides a server-side management interface for Docker resources on edge devices. Commands are proxied through the message bus using a request-response pattern with correlation IDs — the backend sends a command to the device agent and waits for a response (default timeout: 30 seconds).

All routes are mounted under /api/v1/plugins/container/devices/{device_id}/.

Prerequisites

1. The container plugin must be enabled for the tenant (Settings → Plugin Config → Container → Enabled).
2. The target device must be Online with the agent connected.
3. Docker must be installed and running on the device.
4. Your user role must have the appropriate container/* permissions.

Containers

List Containers

GET /api/v1/plugins/container/devices/{device_id}/containers

Returns all containers on the device (running and stopped).

Inspect Container

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}

Returns detailed information about a specific container.

Create Container

POST /api/v1/plugins/container/devices/{device_id}/containers

Create a new container on the device. Request body:

{
  "image": "nginx:latest",
  "name": "my-nginx",
  "ports": ["80:80"],
  "env": ["ENV_VAR=value"],
  "volumes": ["/host/path:/container/path"],
  "restart_policy": "always"
}

Container Lifecycle Actions

All lifecycle actions are POST requests:

Action	Endpoint	Description
Start	/containers/{id}/start	Start a stopped container
Stop	/containers/{id}/stop	Gracefully stop a running container
Restart	/containers/{id}/restart	Stop and start a container
Kill	/containers/{id}/kill	Force-kill a container (SIGKILL)
Pause	/containers/{id}/pause	Freeze all processes in a container
Unpause	/containers/{id}/unpause	Resume a paused container

Remove Container

DELETE /api/v1/plugins/container/devices/{device_id}/containers/{id}

Container Logs

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}/logs

Retrieve container log output. The maximum number of lines is controlled by the max_log_lines configuration (default: 1000).

Container Stats

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}/stats

Returns CPU, memory, network, and I/O statistics for a running container.

Images

List Images

GET /api/v1/plugins/container/devices/{device_id}/images

Inspect Image

GET /api/v1/plugins/container/devices/{device_id}/images/{id}

Pull Image

POST /api/v1/plugins/container/devices/{device_id}/images/pull

Request body:

{
  "image": "nginx:latest"
}

Private registries configured in the plugin settings are used for authentication automatically.

Remove Image

DELETE /api/v1/plugins/container/devices/{device_id}/images/{id}

Volumes

List Volumes

GET /api/v1/plugins/container/devices/{device_id}/volumes

Create Volume

POST /api/v1/plugins/container/devices/{device_id}/volumes

Request body:

{
  "name": "my-data",
  "driver": "local"
}

Remove Volume

DELETE /api/v1/plugins/container/devices/{device_id}/volumes/{name}

Networks

List Networks

GET /api/v1/plugins/container/devices/{device_id}/networks

Create Network

POST /api/v1/plugins/container/devices/{device_id}/networks

Request body:

{
  "name": "my-network",
  "driver": "bridge"
}

Remove Network

DELETE /api/v1/plugins/container/devices/{device_id}/networks/{id}

Configuration

Configure the container plugin under Settings → Plugin Config → Container (tenant-wide) or per device group.

Setting	Default	Description
Registries	—	Private Docker registry URLs for image pulls
Command Timeout	30	Seconds to wait for a device response before timing out
Max Log Lines	1000	Maximum number of log lines returned per request

Group-level Registry Override

Device groups can override the tenant-level registry list. This allows different groups to pull from different registries. Open Devices → Groups → [Group] → Plugins → Container to set the override.

RBAC Permissions

Resource	Action	Description	Default Roles
container/container	read	View containers, logs, stats	viewer, operator, tenant_admin
container/container	manage	Create, start, stop, restart, kill, pause, unpause, remove	operator, tenant_admin
container/image	read	View images	viewer, operator, tenant_admin
container/image	manage	Pull and remove images	operator, tenant_admin
container/volume	read	View volumes	viewer, operator, tenant_admin
container/volume	manage	Create and remove volumes	operator, tenant_admin
container/network	read	View networks	viewer, operator, tenant_admin
container/network	manage	Create and remove networks	operator, tenant_admin

How It Works

Browser → HTTP API → Backend container plugin
                     → Message Bus (cmd.plugin.container.request)
                     → umoo-agent on device
                     → Docker daemon
                     ← Response (evt.plugin.container.response)
                     ← HTTP response to browser

1. The browser sends an HTTP request to the container plugin API.
2. The plugin creates a CommandEnvelope with a unique correlation ID.
3. The command is published to the device's bus topic.
4. The agent executes the Docker command and publishes a ResponseEnvelope.
5. The plugin matches the response by correlation ID and returns it to the browser.

Troubleshooting

"Device timeout" (504):

• The device may be offline or unreachable. Check device status.
• Docker may not be running on the device.
• The agent may not have the container plugin enabled.
• Increase command_timeout for slow operations (e.g., large image pulls).

"Permission denied":

• Your role may lack the required container/* permission. Contact your tenant admin.

Image pull fails:

• Verify the image name and tag exist.
• For private registries, ensure the registry URL is configured in the plugin settings.
• Check device logs for Docker authentication errors.