Running deviceWISE in Docker

The following Asset and Enterprise Gateway products are provided as Docker Images:

• deviceWISE Asset Gateway (amd64, arm64, arm32v7)
• deviceWISE Enterprise Gateway (amd64)

For more information about installing and using Docker, see Get Docker.

Deployment and Management

After installing Docker on your host Operating System, pull the deviceWISE Gateway product of your choice by running the docker pull command.

Installing deviceWISE Gateway Images

The following example demonstrates obtaining the deviceWISE Asset Gateway Image:

# docker pull devicewise/asset-gateway

For deviceWISE Enterprise Gateway, use the following command:

# docker pull devicewise/enterprise-gateway

Alternatively, you can use the docker run command directly, which will pull down the Image automatically, and subsequently launch a Container.

In this example, we launch a Container by the name of dwag01 from the devicewise/asset-gateway Image:

# docker run -d --name dwag01 --net=host devicewise/asset-gateway

For information regarding the available parameters to docker run, please refer to:

• Docker Run

The above examples will deploy the "latest" Tag of the Docker Image. If a specific Tag is required, provide the Tag as follows:

# docker pull devicewise/asset-gateway:21.10.10

To see available Tags, please visit the deviceWISE Docker Hub site.

For the remaining examples in this document, deviceWISE Asset Gateway is used.

After launching a Container instance, connect to the Node through the deviceWISE Workbench.

Managing deviceWISE Gateway Container Instances

After we've successfully pulled the Image and launched a Container instance, the following Docker commands can be used to control the Container instance:

Stopping, Starting, and Restarting the Container:

# docker stop dwag01

# docker start dwag01

# docker restart dwag01

Upgrading deviceWISE Gateway Images

Using the docker pull command, a new Tag can be pulled down from the Docker Hub site. If a specific Tag is not specified, the "latest" Tag will be pulled, replacing any existing "latest" Images in the local Image Registry.

The following is a basic procedure for upgrading a deviceWISE Gateway Image and associated Containers:

1. Using the Workbench, perform a Node back-up
2. Stop any instances of the Docker Containers tied to the current Image using the docker stop command.
3. Remove the Container instances using the docker rm command.
4. Pull the desired Image from Docker Hub using the docker pull command.
5. Launch a new Container from the updated Image, using the docker run command.

Example:

# docker stop dwag01
# docker rm dwag01
# docker pull devicewise/asset-gateway:22.01.01

# docker run -d --name dwag01 --net=host devicewise/asset-gateway:22.01.01

Advanced Usage and Examples

Docker provides many tools and techniques to the user to allow for highly-customized deployments. Visit Docker Docs for the most complete and up-to-date information.

https://docs.docker.com/

The following are a few examples which demonstrate specific deviceWISE Gateway deployment scenarios.

Port Mapping with deviceWISE Gateway Containers

The deviceWISE Gateway services running in the Container listen on several ports. In the previous examples, the --net=host parameter simply mapped any port in the Container to the same port in the Host. However, it may be required to explicitly state which ports should be exposed on the Host for communication with the running Container:

https://docs.docker.com/config/containers/container-networking/

In the case of using the Workbench to access the deviceWISE Gateway Container instance, UDP port 4009 and TCP port 4012 must be published to the outside world:

# docker run -d --name dwag01 -p 4009:4009/udp -p 4012:4012 devicewise/asset-gateway:21.10.10

In the above, port 4013 refers to the host machine and 4012 refers to inside the Container. The port 4012 which is inside the Container is mapped to port 4013 which is outside (host). It is possible to change the host ports and connect to multiple instances of the deviceWISE node.

Other notable ports include:

Using Host Volumes with deviceWISE Gateway Containers

The deviceWISE Gateway service stores persistent data in several SQLite database files, located in a specific sub-directory withing the deviceWISE Gateawy installation path. These files persist across a general deviceWISE upgrade on most platforms.

However, the nature of Docker Images and Containers prevents the user from using this persistence when creating a new Docker Container from a Docker Image. It is suggested that the Node Backup and Restore procedured be followed in the general case when upgrading the deviceWISE Docker Image.

In some cases, it may be beneficial to have the deviceWISE SQLite database files stored in a location OUTSIDE of the running Docker Container instance. This can be achieved using Docker Volumes:

• Use volumes

In the following example, we demonstrate creating a Docker Container with the db sub-directory located in the host file system, and exported to the Docker Container instance.

# mkdir -p /var/devicewise/dwag01-db
# docker run -d --name dwag01 --net=host -v /var/devicewise/dwag01-db:/dw/db devicewise/asset-gateway:21.10.10

Upon initial Container launch, The deviceWISE Gateway service will populate the database directory with several database files, and these files will be located in the /var/devicewise/dwag01-db directory with the host OS file system.

Now, if you upgrade the Docker Image, you can spin-up a new Container instance using the previously created and populated database files.

# docker stop dwag01
# docker rm dwag01
# docker pull devicewise/asset-gateway:22.01.01

# docker run -d --name dwag01 --net=host -v /var/devicewise/dwag01-db:/dw/db devicewise/asset-gateway:22.01.01

deviceWISE will load all of the previous Devices and Triggers created and used with the previous instance.

Building Custom deviceWISE Gateway Images

Docker builds Images automatically by reading the instructions from a Dockerfile. Similar to a traditional Makefile, it contains commands specifying how to build a Docker Image.

For more information about building Docker Images, and the format and syntax of a Dockerfile, visit:

• Dockerfile reference
• Sample application
• Best practices for writing Dockerfiles

A Docker Image consists of read-only layers, each of which represent a Dockerfile instruction. The layers are stacked and each one is a delta of the changes from the previous layer. Consider this Dockerfile:

FROM devicewise/asset-gateway:21.10.10

WORKDIR /dw/dwcore
COPY dw.dwadvanced.Linux-X64-Generic.*.pkg /dwcore/temp/
COPY dw.dwsandbox.Linux-X64-Generic.*.pkg /dwcore/temp/RUN ./dwpackageinstaller -i temp/dw.dwadvanced.Linux-X64-Generic.*.pkg -filetracker package_installer.file.tracker.txt -tmpdir package_installer -confirmation logs/confirmation.json -stagingdir ../staging -dbdir ../db/ -logdir logs

RUN ./dwpackageinstaller -i temp/dw.dwsandbox.Linux-X64-Generic.*.pkg -filetracker package_installer.file.tracker.txt -tmpdir package_installer -confirmation logs/confirmation.json -stagingdir ../staging -dbdir ../db/ -logdir logs

Each instruction creates one layer:

• FROM creates a Layer from the devicewise/asset-gateway:21.10.10 Docker Image.
• COPY adds files from the directory in which the docker build command is executed.
• RUN runs the command specified. In this example, we install the two Packages specified when the Container is launched for the first time.

The following is a demonstration of how to build the Image:

# mkdir devicewise-custom-image

# cd devicewise-custom-image
# docker build -t devicewise/asset-gateway-custom:21.10.10

...where the contents of the directory include:

1. The Dockerfile containing the contents above
2. Two deviceWISE Packages, obtained from the Portal and copid in the the directory

After executing the docker build command, you now have an Image of the deviceWISE Asset Gateway runtime, along with the dwadvanced and dwsandbox Packages ready to go.

Some benefits of creating your own custom Image include:

• Installation of Packages
• Configuration of Devices and Triggers
• Tuning the deviceWISE Runtime Properties
• Installation of Custom Applications
• System and Network Configuration

Using the flexibility of Docker, you can create a custom Docker Container based on deviceWISE Gateway that can be used to meet any special requirements.

Using Docker Compose for Custom Deployments

If you use Docker extensively, managing multiple Containers can become tedious. Docker Compose helps to overcome this issue by enabling the user to build and deploy multiple Containers.

This not only allows you to spin-up more than one Container at a time, it also provides the ability to tap-in to additional Docker featurs, such as mapping network ports and using Volumes. For more information on Docker Compose, visit:

• Install Docker Compose
• Overview of Docker Compose

Here we have an example docker-compose.yml file:

version: "3"
services:
	dwag-compose-example-01:
	image: devicewise/asset-gateway:21.10.10
ports:
	- 4012:4012
volumes:
	- /var/devicewise/dwag01-db:/dw/db
	dwag-compose-example-02:
	image: devicewise/asset-gateway:21.10.10
ports:
       - 4013:4012
volumes:
	- /var/devicewise/dwag02-db:/dw/db

We now run docker compose up (or alternatively, docker-compose up; see: Install Docker Compose) in the directory containing the docker-compose.yml file. We now have 2 deviceWISE Asset Gateway Container instances based on the devicewise/asset-gateway:21.10.10 Image running on the same hosts, each available on their own ports (4012 and 4013).