How to package a Docker application

Overview

Once you learn how to successfully deploy out-of-the-box apps from Barbara Marketplace, you’re ready to start deploying your own Docker applications. For this, you should be familiar with Docker containers and creating Docker applications using Docker compose files.

Before deploying your own apps, make sure your Edge Node isn’t resource constrained. Consider removing some or all of the previous apps explained in this tutorial before deploying your own Docker containers. Apps are removed by opening the respective App card in the Edge Node details view. Select the “X” to the right of the app’s name on the App card and the application is deleted from that Edge Node. This action doesn’t remove the app from any of your other Edge Nodes in Barbara PANEL.

Remove some apps

7.1 How to package a Docker app for deployment

Barbara Edge applications need to be packaged in ZIP files before they can be deployed to your Edge Node. The ZIP directory structure must include a docker-compose.yaml file in the root. Including a ./persist folder as well is highly recommended, following the guidelines below:

• docker-compose.yaml is the Docker Compose file, i.e. the mail file that lets the Docker daemon know what services to use as well as other details related to their orchestration (find out more by reading https://docs.docker.com/compose/)
• persist is the folder that contains all the content your app should keep (e.g. binary files, certificates, etc.)

Once you create this structure on your local computer and compress it to a ZIP file, your app is almost ready to deploy. We recommend reading through some handy Docker tips and tricks first:

7.2 Barbara Docker tips and tricks

While creating the ZIP file, consider these crucial points:

• Docker-compose YAML files can only be named docker-compose.yaml or docker-compose.yml, otherwise, Docker installation fails.
• All persistence files/folders must be placed inside the persist folder in the ZIP root folder.
• You can add other files/folders into the ZIP folder to be used to build containers, but note that they are replaced/deleted if the docker app is updated.
• Native Docker volumes are also allowed.
• Only bind mounts are allowed, but only if the mount point (host side) contains ./persist/, ./appconfig or ./sys/ at the beginning.
• Privileged containers are not allowed.
• Admin-related capabilities are not allowed.
• Device access must be declared explicitly which means you have to add the following text within your docker-compose.yaml file.

devices:
  HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]

For example:

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm" 

7.3: Deploy your newly created app

Your Edge applications are organized in the App Library. Open the Library by selecting the Library button in the top menu on Barbara PANEL.

New App

1. With the Library view open, select the “NEW APP” button on the top right, and a NEW APPLICATION modal opens. Add the necessary information, making sure “User Docker” is selected.

New Version

2. Once the application is created, upload the ZIP file (this is the first version of the application).
3. In the Library view, select the name of the new application created, click “ADD VERSION” on the top right and fill in the necessary information.

Congratulations! Your application is ready to be deployed! Now follow the same steps used to deploy the demo applications included in the App Starter Kit:

1. Open the Edge Node Lists view by clicking the Nodes button on the top menu of Barbara PANEL
2. Select the Edge Node you want to deploy the app to from the NODE NAME list.
3. Click the “NEW CARD” button, choose “User Docker App” as the type, and then click “ADD”.
4. Select the application and the version you want to run and click “SEND”.
5. The Edge Node details view opens, displaying your new Docker App card.
6. Open the “LOG” dropdown list and activate the logs, so you can check the status of your deployment.

If you encounter any issues while your application is starting up, please contact the Barbara support team.

7.4 Managing variables within your application - APP-CONFIG and SECRETS

Just like the apps included in the App Starter Kit, Docker applications use SECRETS, CREDENTIALS, GLOBAL APP-CONFIG and LOCAL APP CONFIG. These are files that contain dynamic information that can be read from inside your application. Sensitive data such as usernames and passwords to access your app are configured in SECRETS or CREDENTIALS. Other data like URL, IP, and ports the app connects to, are configured in LOCAL or GLOBAL APP-CONFIG.

• CREDENTIALS are used to login to private docker repositories, so you can download images from them. They are not accessible from the apps, the system or the Docker daemon.
• SECRETS are global variables that are defined in your Edge Node and can be referenced by the apps you install. For example, the apps in the App Starter Kit require configuring a series of SECRETS before each app can be deployed to an Edge Node. If you establish a SECRET you can reference it in your application’s code by using the SECRET name as the variable name (shown in the images below).

Name your secret

How to establish a SECRET in Barbara PANEL

Establish a Secret

How to reference a SECRET in your app’s code

Your variables can be organized however you prefer. The Barbara support team is happy to answer any questions that come up while developing your applications.

To ensure your SECRETS, GLOBAL and LOCAL APP-CONFIG variables are accessible from your applications, the following volume mounts must be added to your app’s Docker Compose YAML file:

Reference a Secret

Once the volumes are mounted, you have access within the Docker container to these two files: /appconfig/global.json and /appconfig/appconfig.json.

Both files are kept updated with the content in Barbara PANEL, and they react to any changes made. All you need to do is add a function to the application in charge of reading the files and using the data therein for the app’s configuration.

For example, if you add the following object to your Local App Config File and click “SEND”, you can access it from within your Docker container. You would be accessing a local JSON file (shown in the image below).

App config

This is an example of a Python program accessing the following variable:

Python Example