Deploying

Deviceplane supports the deployment and updating of user applications packaged as Docker containers. Here is the specific terminology regarding deployments in Deviceplane.

  • A service defines the specification for a container that should be deployed.
  • An application defines a group of related services that represent a logical "application" to a user.
  • An application config is a file in Docker Compose format that defines all of the services in an application.
  • A release is a new version of an application config that will be deployed to devices.

Applications can be created in the Deviceplane UI. When an application is first created it has no releases meaning no containers will be deployed as a result of the application. Containers will be deployed once an initial release is created.

By default an application will run on all devices in a project. To configure an application to run on a subset of devices set a scheduling rule.

Application Configs

An application config is a file in Docker Compose format that defines all of the services in an application. Deviceplane specifically implements the v1 format as it was the simplest version and the features from later versions do not apply to deploying in Deviceplane.

Here is an example of a Deviceplane application config.

service1:
image: nginx
service2:
image: ubuntu
command: [ sleep, infinity ]

A comprehensive list of flags available can be found in the Docker documentation. All differences between Deviceplane application configs and Docker Compose are noted below.

Compose DirectiveDifference in Deviceplane
buildNot supported (only applicable for development purposes)
dockerfileNot supported (only applicable for development purposes)
exposeUse ports instead
volumesOnly bind mount volumes will work in Deviceplane. Any other type of volumes are not supported.

Releasing

Releasing an application consists of setting a new application config. The changes reflected in this new version will then be deployed to all relevant devices. Let's walk through an example of releasing and explain the exact steps that will be taken by Deviceplane. The initial application config is a single service running nginx with image tag 1.16 and exposed on port 8080 on the host.

example:
image: nginx:1.16
ports:
- 8080:80

Then let's suppose we create a new release and update the application config to instead have the port bound to port 9090 on the host.

example:
image: nginx:1.17
ports:
- 8080:80

Once this release is created the deployment process will begin to relevant devices. On each specific device the upgrade process will be performed as follows.

  1. The image for the new release is pulled to the device
  2. The previously running container with image nginx:1.16 is stopped and then removed
  3. A new container is created with image nginx:1.17
  4. The new container is started

Releasing via the UI

From the applications page, choose an individual application and then click the "Create New Release" button. You'll be brought to an editor where you can enter a new application config. Once submitted a new release will be created and the standard deployment procedure will begin.

The online editor supports YAML highlighting and code folding on top-level YAML keys.

Reverting to an old release (creating a new release based on the application config from an older release) is also possible via the UI. To do this click on an old release on the overview page for an application and then click "Revert to this Release".

Releasing via the CLI

View the CLI documentation for information on how to setup and configure the CLI.

There are two commands that can be used to deploy via the CLI: deviceplane deploy and deviceplane edit.

deviceplane edit

The deviceplane edit command opens the application config from the latest release in your system's default editor. Once open you can make whatever changes you'd like to the application config and then upon exiting the editor those changes will be submitted as a new release.

This command is useful for rapidly updating application configs in development and staging environments.

deviceplane deploy

The deviceplane deploy command creates a new release from a local application config file. Popular naming conventions for this file include deviceplane.yml, deviceplane-<application_name>.yml, and <application_name>.yml.