> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md).

# Cybus::Container

Run a Docker image of your choice as part of a service, with volumes, port mappings, and resource limits set in the service commissioning file.

The **Cybus::Container** resource runs a Docker container that can communicate with the internal MQTT broker of Connectware. Use it for any data processing or presentation that you can package as an image, such as data analytics in Python or a Grafana dashboard.

{% hint style="warning" %}
This resource works only in Docker Compose deployments of Connectware. In a Kubernetes deployment, it results in an error.
{% endhint %}

## Container Properties

| Property                    | Type       | Required     | Default          |
| --------------------------- | ---------- | ------------ | ---------------- |
| [capAdd](#capadd)           | `enum[]`   | Optional     |                  |
| [command](#command)         | `string[]` | Optional     |                  |
| [cpus](#cpus)               | `number`   | Optional     | `0.0`            |
| [devices](#devices)         | `object[]` | Optional     |                  |
| [entrypoint](#entrypoint)   | `string[]` | Optional     |                  |
| [environment](#environment) | `object`   | Optional     |                  |
| [image](#image)             | `string`   | **Required** |                  |
| [labels](#labels)           | `object`   | Optional     |                  |
| [memory](#memory)           | `integer`  | Optional     | `0`              |
| [ports](#ports)             | `string[]` | Optional     |                  |
| [privileged](#privileged)   | `boolean`  | Optional     | `false`          |
| [restart](#restart)         | `enum`     | Optional     | `unless-stopped` |
| [ulimit](#ulimit)           | `integer`  | Optional     |                  |
| [volumes](#volumes)         | `string[]` | Optional     |                  |
| [workingDir](#workingdir)   | `string`   | Optional     |                  |

### capAdd

The Linux kernel capabilities to add to the container.

* **Optional**
* Type: `enum[]`
  * Must be one of the following values: `ALL`, `AUDIT_CONTROL`, `AUDIT_WRITE`, `CHOWN`, `DAC_OVERRIDE`, `DAC_READ_SEARCH`, `FOWNER`, `FSETID`, `IPC_LOCK`, `IPC_OWNER`, `KILL`, `LEASE`, `LINUX_IMMUTABLE`, `MAC_ADMIN`, `MAC_OVERRIDE`, `MKNOD`, `NET_ADMIN`, `NET_BIND_SERVICE`, `NET_BROADCAST`, `NET_RAW`, `SETFCAP`, `SETGID`, `SETPCAP`, `SETUID`, `SYSLOG`, `SYS_ADMIN`, `SYS_BOOT`, `SYS_CHROOT`, `SYS_MODULE`, `SYS_NICE`, `SYS_PACCT`, `SYS_PTRACE`, `SYS_RAWIO`, `SYS_RESOURCE`, `SYS_TIME`, `SYS_TTY_CONFIG`, `WAKE_ALARM`

### command

The command to run in the container, as a list of strings.

* **Optional**
* Type: `string[]`

### cpus

How much of the CPU resources of the host the container can use, in CPUs. For example, if the host has two CPUs and you set `1.5`, the container can use at most one and a half of them. `0` sets no limit. To set a limit, specify a non-zero value.

* **Optional**
* Type: `number`
* Default: `0.0`

### devices

The host devices to add to the container. Each item is an object with the required keys `PathOnHost`, `PathInContainer`, and `CgroupPermissions`.

* **Optional**
* Type: `object[]`

### entrypoint

The entry point of the container, as a list of strings.

* **Optional**
* Type: `string[]`

### environment

The environment variables of the container, as names and values. A value can be a string, an integer, or a boolean.

* **Optional**
* Type: `object`

To give the container the connection details of the Connectware MQTT broker, pass the [global pre-defined parameters](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#global-pre-defined-parameters):

{% code lineNumbers="true" %}

```yaml
myServiceContainer:
  type: Cybus::Container
  properties:
    image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0
    environment:
      CYBUS_MQTT_HOST: !ref Cybus::MqttHost
      CYBUS_MQTT_PORT: !ref Cybus::MqttPort
      CYBUS_MQTT_USER: !ref Cybus::MqttUser
      CYBUS_MQTT_PASSWORD: !ref Cybus::MqttPassword
```

{% endcode %}

### image

The image to run, in the form `<registry>/<name>:<tag>`. The image specifier has the following parts:

* Optional: The address of the registry, which is the domain name of the registry server, for example `registry.cybus.io`.
* The image name, written as a plain name or as a path, for example `alpine` or `cybus-services/baz-dashboard`.
* Optional: The image tag, usually the version, for example `0.2.0`.

A basic image specification names only the image. The following specification runs the Alpine Linux image with the `latest` tag from Docker Hub:

{% code lineNumbers="true" %}

```yaml
image: alpine
```

{% endcode %}

A full image specification also names the registry and the tag. The following specification runs version `0.2.0` of the image `cybus-services/baz-dashboard` from the Cybus registry:

{% code lineNumbers="true" %}

```yaml
image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0
```

{% endcode %}

When Connectware creates the container, it pulls the image from its registry only if the image is not on the Docker host yet. To get a newer version of an image, use a new tag. For the Cybus registry at `registry.cybus.io`, Connectware uses your current license key as the credentials. You can also use public images from Docker Hub, or images from other private registries.

* **Required**
* Type: `string`

### labels

User-defined metadata for the container, as keys and values.

* **Optional**
* Type: `object`

### memory

The maximum amount of memory that the container can use, in bytes. `0` sets no limit. To set a limit, specify a non-zero value. Docker accepts a limit of 6 MB (6291456 bytes) or more.

* **Optional**
* Type: `integer`
* Default: `0`

### ports

The port mappings between the host and the container. Each item has the form `<hostPort>:<containerPort>`.

* **Optional**
* Type: `string[]`

### privileged

Whether the container is privileged, that is, whether it has full access to the host.

* **Optional**
* Type: `boolean`
* Default: `false`

### restart

What Docker does when the container exits.

* **Optional**
* Type: `enum`
  * Must be one of the following values: `no`, `always`, `on-failure`, `unless-stopped`
* Default: `unless-stopped`

### ulimit

The maximum number of open files per process in the container. Connectware sets both the soft and the hard `nofile` (number of files) limit to this value. Without `ulimit`, the system default or the default of the Docker environment applies.

The limit concerns shared resources. So some Docker hosts do not allow changing it, especially when the Docker host runs in a virtualized environment.

* **Optional**
* Type: `integer`
* Minimum: `1024`

### volumes

The volumes to mount into the container. Each item has the form `<volume>:<pathInContainer>`. To mount a [Cybus::Volume](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-volume.md) resource, reference it with `!sub`, as shown in the [example](#example).

* **Optional**
* Type: `string[]`

### workingDir

The working directory for the commands that run in the container.

* **Optional**
* Type: `string`

## Volumes and Files

To give a container files from the service commissioning file, declare them as [Cybus::File](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-file.md) resources. Connectware writes them into a [Cybus::Volume](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-volume.md). The container accesses them when it mounts that volume with the [volumes](#volumes) property.

## Container Name

Connectware names the container after the [service ID](https://docs.cybus.io/data-flows/services/serviceid.md) and the [resource ID](https://docs.cybus.io/data-flows/service-commissioning-files/resources.md#resource-id), joined by a hyphen. For example, the resource `my_container` in the service `myService` runs as the container `myService-my_container`.

The container name is also the hostname that the application inside the container sees. Other containers of the same service reach the container by this name.

The container name can have at most 63 characters, because it is used as the hostname. Connectware rejects a longer name with an error. See [Service ID Length Restrictions](https://docs.cybus.io/data-flows/services/serviceid.md#service-id-length-restrictions).

## Docker Networks

Connectware runs the containers of each service in a separate Docker network, named after the [service ID](https://docs.cybus.io/data-flows/services/serviceid.md). This network connects the containers of the service with each other and with the ingress proxy of Connectware, which they reach as `connectware`.

All containers of one service can communicate securely with each other, but cannot interfere with the containers of other services. To allow connections from other services or from outside Connectware, define [Cybus::IngressRoute](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-ingressroute.md) resources.

Enabling or disabling a service with containers can temporarily interrupt connections of outside clients to Connectware. The interruption can occur only when you enable or disable such a service. See [Docker Problem with Network Changes](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container/docker-problem-with-network-changes.md).

## Example

{% code lineNumbers="true" %}

```yaml
myVolume:
  type: Cybus::Volume

myServiceContainer:
  type: Cybus::Container
  properties:
    image: registry.cybus.io/cybus-services/baz-dashboard:0.2.0
    volumes:
      - !sub '${myVolume}:/data'
    ports:
      - 8080:8080
    environment:
      LOG_LEVEL: info
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
