Docker Runtime

With the Docker Runtime you can run arbitrary apps packaged as docker images.

Private beta

The Docker Runtime is currently in private beta with select users. It is planned for public release in Q4 2019 (see the Q4/19 Roadmap Update for more information). To stay up to date about upcoming releases please check out our blog, where we post release notes and roadmap updates.

Contents

Docker apps

A docker app is a type of ActyxOS app where the business logic is implemented in one or more docker images. At runtime, ActyxOS launches a docker container for each image, thus running your logic.

my docker app

Technically, and as shown in the above image, a docker app is composed of

  1. an ActyxOS app manifest (a JSON file),
  2. a docker-compose.yml file specifying how to run your containers; and,
  3. one or more docker images (identified by their tag).

An app manifest is a JSON file that describes the app to the Actyx platform. For docker apps it has the following syntax (based on the example image above):

Usage

Building docker apps

Through the development process of your app, you may use any tools you would like to implement your business logic and build your docker images. You can also use any existing images you want to build on.

Docker documentation

Please refer to the Docker Documentation for more information about how to build and compose docker images.

Packaging docker apps

Once you are finished with the development, you can use the Actyx CLI to package your app for deployment to an edge device running ActyxOS.

The Actyx CLI provides the ax app:package command for packaging your app for deployment. The command will read the app manifest, validate the docker-compose file, save all necessary images and generate a tarball for deployment.

For docker apps, the manifest (manifest.json) should be structured as follows:

{
    "docker": {
    "name": "MyApp",
    "version": "1.0.3",
    "docker-compose": "./docker-compose.yml",
}

Note

There is no need to specify necessary images in the manifest since the Actyx CLI will automatically analyze the docker-compose file to figure out which images need to be deployed.

How this works is shown in the following short example.

# Go to project directory
$ cd my-docker-app/
# Package the app
$ ax app:package manifest.json
> Packaging docker app...
> MyApp (1.0.3) App successfully packaged (MyApp-1.0.3.tar.gz)

Deploying docker apps

The Actyx CLI provides the ax app:deploy command for deploying apps to edge devices. In the background, the CLI will automatically read the mainfest file, inform the edge device (or, more accurately, ActyxOS on the edge device) about the deployment and perform any necessary data transfers.

Local deployments only

Currently, the Actyx CLI only supports local interaction with devices (using the --local flag). We plan to release remote deployment functionality in 2020. Please check out our blog for release updates.

See this example for how to use the ax app:deploy command:

# Go to project directory
$ cd my-docker-app/
# Deploy the app
$ ax app:deploy --local MyApp-1.0.3.tar.gz EdgeDevice1
> Deploying docker app...
> MyApp (1.0.3) (MyApp-1.0.3.tar.gz) successfully deployed to EdgeDevice1 (10.7.0.32).

Once an app has been deployed to an edge device, the ActyxOS Docker Runtime will automatically start and run it. Unless your app’s containers stop themselves, they will run indefinitely. If the edge device is restarted, your app will also automatically be restarted.

Monitoring docker apps

Since you cannot access your app’s containers directly, monitoring means accessing logs they generate. The AcytxOS Docker Runtime automatically persists any text sent to any containers stdout or stderr. Preferably, your app generates logs using the Console Service.

You can access and tail (use the --tail flag) these logs using the ax logs command.

Only local mode until 2020

The Actyx Console will be released in 2020. Until then only local access to edge devices is possible (using the --local flag). Please check out the blog for future release updates.

See the following example for how this currently works.

$ ax logs --tail --local MyEdgeDevice1
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.106Z [info] Starting server...
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.113Z [debug] Signals:
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.113Z [debug]   - tempSensor1
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.113Z [debug]   - tempSensor2
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.114Z [debug]   - tempSensor3
> MyApp-1.0.3::opcservice::stdout | 2019-09-11T21:46:12.114Z [debug]   - tempSensor3
> MyApp-1.0.3::cassandra1::stdout | 2019-09-11T21:46:13.009Z [info] Cassandra listening on 0.0.0.0:3919

Undeploying docker apps

Undeploying an app means deleting it from the device. This can be done with the ax app:undeploy command.

Example:

# Undeploy an app
$ ax app:undeploy --local MyApp EdgeDevice1
> Undeploying app `MyApp`...
> App 'MyApp' (1.0.3) successfully undeployed from EdgeDevice1 (10.2.8.39)