Docker Applications
EDGEHOG Apps Manager allows managing applications based on Docker Containers on the devices remotely, in a secure way. It is possible to deploy applications and manage operations such as Install, Start, Stop, Upload remotely, even on multiple devices simultaneously.
Docker
Docker is a platform for developers and sysadmin to build, share, and run applications with containers. The use of containers to distribute applications is called containerization. Containers are nothing new, but their use to easily distribute applications is.
A Docker Container is launched by running an image. An image is an executable package that includes everything needed to run an application--the code, runtime, libraries, environment variables, and configuration files.
A container is a runtime instance of an image--what the image becomes in memory when executed (that is, an image with the state, or a user process).
Docker container images are stored on online servers called Registry which also take care of distribution.
Docker Compose
Docker Compose is a tool to define and run multi-container Docker applications. With Compose, you use a YAML file to configure your application's services, so with a single command, you create and launch all services from the configuration. Check the official docker-compose documentation for more info.
Applications/Apps
By Application/App we mean a set of containers (complete architecture/structure) linked together, defined by a Docker Compose YAML file. Each App is therefore defined by a name and the relative YAML file that must be able to be loaded into the EDGEHOG system from the interface.
The customer can manage their apps as well as third-party apps on the gateways on their own and deployed these apps across the entire fleet of gateways.
It is also possible to manage Docker Applications whose container images are stored on private registries with access by credentials.
To create an App select Create Application.
Then enter:
Application Name;
Description;
Check if Start On Install/Update: If this box is checked, the application will start automatically after each Installation or Update operation performed on a device.
Gateway Types: Select the types of gateways that will be compatible with this Application on which you can deploy.
Select Tags;
Upload Configuration File (the Docker Compose YAML file): Once loaded the Configuration File will be validated by the system and the table below will show the individual services (containers) of which the application is composed.
The uploaded file .yamlmust be formatted correctly following the YAML rules, to be accepted by the system, and need to be a valid Docker Compose file, to make the application work correctly. Use Docker Compose file version 3 by declaring it at the beginning of the YAML like this:
version: "3"
Pull from a private repository. If the Docker images of the containers that compose the App are stored on a private registry with access via credentials, you can tick the checkbox to open the relative options. The Docker registries that comply with the Docker Registry V2 API specification are supported (e.g. Docker Hub, AWS ECR, Google CR).
Registry URL: the URL of the registry where the docker images are stored. If the Registry used is a private Docker Hub account, the field should be left empty.
Registry Username: The username used to authenticate to the private Registry.
To operate on a Docker Application contained in a private registry, such as updating the application, each device needs to have information about the Registry URL from which to download the images of the containers and the credentials to log in to the private registry account such as Username and Token or Password. The devices will use this information to log in to the registry using docker login.
For security reasons, EDGEHOG has chosen not to store on its servers the passwords or tokens for authentication to the private registry where the docker container images are stored. Passwords or tokens will be requested each time an install or update operation is performed on the Docker App, on a single device or in a fleet campaign. The Registry URL and Account Registry fields will also be sent to devices each time an operation is performed but are stored in the Application entity for user convenience.
In this section a list of all created apps and their details is available.
Here it’s possible to select a single app clicking on the line. Once the app is selected the App page is going to open.
To edit an app, simply modify the fields or load a new Configuration File and press the Save button.
As we saw in the OS Campaigns, the table on the right of the page is updated with the number of gateways that can be updated as information is selected and added in the filter fields on the left.
As you select and add information in the filter fields on the left, the table on the right of the page is updated with the number and specifications of the gateways that OS can be updated to.
To create an App Campaign select:
Application: select the App from the list;
Operation: Install/Update, Install, Update, Start, or Stop, these are the commands that can be sent to each device that is part of the campaign, relative to the application chosen. The devices will use the Docker Compose commands to perform the selected operations (e.g.
docker-compose up,docker-compose down,docker-compose pull)Name: enter the Campaign Name;
Tags: Through the tags, you can filter the devices of the fleet to which the campaign should arrive.
Rollout Rate: Specifies the maximum number of devices that will be informed of the update per minute;
Execution Timeout: Specifies the maximum amount of time (in minutes) a device should take to install the update.
If the operation on the individual device is not completed (with success or error) before the end of the Execution Timeout, the campaign will report the Timeout status on that device. The server will no longer wait for a response from the device, which may continue operations in the background and complete them successfully despite the online interface reports the Timeout.
Once you have entered all the parameters you can create the App Campaign by clicking on the button Create Application Campaign. You will be redirected to the status page of the App Campaign to see the status of each device being updated.
Once you have filtered the right devices you can create the campaign by clicking on the create application campaign button. You will be redirected to the status page of the campaign where you can Start it and refresh the page to check the status of each device being updated.
If the selected application of the campaign is contained in a private registry, and an Install or Update operation is chosen, a popup for entering authentication credentials will be displayed at Start.
The popup shows the Registry URL and Registry account data saved in the application. Besides, you will need to enter the Token or Password to enable the device to authenticate with a private registry.
There is a known problem in AWS ECR private registry integration. Sometimes the installation/update of container images stored in ECR registries returns "no basic auth credentials" error. If you encounter this error message, please just retry with the same user and token.
We suggest to always use a Token instead of a Password to log in to a private Registry. Check the documentation provided from your Registry to know how to generate an authentication Token.
In this section a list of all created campaigns and their status is available.
Here it’s possible to select a single campaign clicking on the appropriate line. Once the campaign is selected the Campaign Recap page is going to open.
Inside the page of each device, you can check the status of the associated applications and perform individual operations on each Docker Application. Go to the Device Page for more information.
