Setting Up Docker on Your Device

Overview

Deploying Docker Containers on Devices

1. Create the release.

The way this will work is that a Release endpoint will be implemented where each release will contain the following information

• Version
• Which devices the release applies to
• A number of containers each with the following information
  • Name
  • Which image+tag to run
  • Which tags should be present on the device
  • Startup parameters
  • If data directories should be purged on deploy.

This endpoint will return success when the release is created.

2. The update will then be queued on each referenced device.

This will cause the device to retrieve the active release associated to it, and perform the following actions.

Endpoints

The CRUD endpoints all return “201 Created” or “200 OK” when an entity is created or modified, and the body of the response will contain the created or modified entity. The DELETE method will return “204 No content” on success.

Registry

A registry should be created to allow the device to authenticate against a custom docker registry. The model contains the url and credentials for the custom docker registry. When added, devices will automatically log in to the registry if not already logged in, on startup, and thereby be ready to pull images.

If the image should be pulled through a custom registry, the registry needs to be referenced when creating the container.

Creating a registry is done using this endpoint https://api.autopi.io/#/docker/docker_registries_create

Project

The project endpoint is a wrapper for releases, so to create any releases you must first create a project.

Creating a project is done using this endpoint

POST /docker/projects/

https://api.autopi.io/#/docker/docker_projects_create

Release

The release endpoint is used to create new releases, and contains a list of containers each with metadata and runtime properties for that specific container.

Creating a project is done using this nested endpoint

POST /docker/projects/{project_pk}/releases/

https://api.autopi.io/#/docker/docker_projects_releases_create

Payload

{
   "id": 1,
   "version": "1.0.0",
   "version_hash": "96a7191f",
   "devices": [
       "device_id"
   ],
   "containers": [
       {
           "name": "curveball",
           "image": "curveball",
           "tag": "delta-base-r0.0.0.1",
           "required_tags": [
               "base"
           ],
           "startup_parameters": {
               "environment": "REQUESTS_CA_BUNDLE='/usr/local/share/ca-certificates/AdamCA.crt'",
               "binds": [
                   "/home/balenaEngine/data:/opt/RavenDB/Server/RavenData"
               ],
               "network_mode": "host",
               "restart_policy": "always",
               "privileged": true
           },
           "purge_data": false,
           "registry": 1,
           "fully_qualified_name": "deployment-curveball-1"
       },
       {
           "name": "ravendb",
           "image": "ravendb",
           "tag": "base",
           "required_tags": [],
           "startup_parameters": {
               "environment": "RAVEN_ARGS='--config-path /opt/RavenDB/Server/RavenData/settings.json'",
               "binds": [
                   "/home/balenaEngine/data:/opt/RavenDB/Server/RavenData"
               ],
               "network_mode": "host",
               "restart_policy": "always",
               "privileged": true
           },
           "purge_data": false,
           "registry": 1,
           "fully_qualified_name": "deployment-ravendb-1"
       }
   ],
   "successful_deployments": [
       "device_id"
   ],
   "remove_containers": [
       "curveball",
       "ravendb"
   ]
}

Special Fields

Name	Required	Description
remove_containers	No	Explicitly names the containers which should be handled as ‘initial containers’. On release it will attempt to stop each container, run deployment, and if successful the containers will be removed, or on failure, they will be restarted.
version_hash	Readonly	Alternative autogenerated field (readonly) only used for referencing a release by a generated version.
successful_deployments	Readonly	Will include only devices which has successfully deployed the release.

After a release is created, each device associated to the release will receive the release information, and the release will be applied the next time the device is about to go to sleep, as the device in that situation is considered to be idle. Logging in to registries, removing images, pulling new images, starting containers etc.

The release can also be triggered by executing the following command via the execute endpoint on the devices you want to deploy to.

state.sls docker.release

Device

The device endpoints can be used to retrieve either all devices, or some devices, and includes a new field called docker_releases which can be used to see if a specific release is deployed successfully on the device. The ID is the ID of the release.

Get a specific device https://api.autopi.io/#/dongle/dongle_devices_read

Get all devices https://api.autopi.io/#/dongle/dongle_devices_list

Both endpoints returns device object(s)

{
  "id": "734c361a-ba56-472a-a891-ee2af1a8057v",
  "unit_id": "4e633880-ef6e-4c20-77ed-5761b3de5d4c",
  ...
  "docker_releases": [
	103
  ]
}

 

Modules

Highlighted modules for performing various actions on a running device docker instance.

Executing Module Commands

Module commands is executed on the device through the execute endpoint. See documentation here: https://api.autopi.io/#/dongle/dongle_devices_execute_command

When executing commands remotely, you must execute the command async via the execute endpoint, and then use the https://api.autopi.io/#/dongle/dongle_devices_retrieve_command_result endpoint to poll for the result from the device.

Example payloads for REST API are included below.

Executing Commands Locally On the Device

The above commands can also be executed directly on the device with the following endpoint

POST localhost:9000/dongle/<uuid:unit_id>/execute/

The body should be the same as the above remote command endpoint.

The unit_id can be retrieved one of the following ways

A. Calling the root route

GET localhost:9000

B. Reading it from the file

/etc/salt/minion_id

The reason that you need the unit_id is because we need to make sure that the request is actually meant for that specific device when using the endpoint from another connected device, like when using the local configuration tool.

Container Logs

Logs are retrieved from the containers by using the docker module.

docker.logs CONTAINER_NAME

Example payload for executing via REST API

{
  "command": "docker.logs",
  "arg": [
	"CONTAINER_NAME"
  ],
  "kwarg": {}
}

5.3. Device Logs Logs are retrieved from the device by using the minionutil module.

minionutil.last_logs

See documentation site for all parameters minionutil.last_logs

Example payload for executing via REST API

{
  "command": "minionutil.last_logs",
  "arg": [],
  "kwarg": {}
}

Let's keep in touch!

Thank you for choosing AutoPi. We're excited to see what you will achieve with your AutoPi device!

Buy AutoPi device Check out our shop .

Learn more Check which device fits your requirements .

Contact our sales team You can build on top of AutoPi .

Get help from our support team Let us know about your technical questions.