Getting Started ‐ Build and Compose
In this section, activities regarding image and container creation for running an application in the Docker environment will be described. On this page, there are two sections:
The Image building section focuses on the details of commands to use while building your Docker image, while the Image Composing section focuses on creating a container for the image to run in.
To set up any application or environment that should run with Docker, an image of your working environment is required, so that the dockerized image has all the necessary tools to run its functionalities. Now that you've written a Dockerfile, the next logical step is to build it, creating the summarized environment of your application that will run on the Docker.
We've created an application and written a Dockerfile. The Dockerfile should now be built and pushed to a registry or saved to a local environment, so that it can be pulled from another device. To build the image, make sure to position yourself inside the directory you created your Dockerfile in, then open a terminal to write the following line:
docker build -t registry-name:1.0.0 .
This command builds a Docker image from the directory you are positioned in, using all that is specified in the Dockerfile. For this example, the image was also tagged registry-name:1.0.0, which names the repository registry-name, with the tag 1.0.0. The build process usually takes a bit more time, but it depends on the size of the base image, services that need to be installed and general required actions. If an error occurs, it is most likely due to the environment setup in the Dockerfile or a service that can't be reached.
After the image is built, one can either push it to a repository or create a .tar file that is a UNIX-based utility used for collecting a large number of files into one archive file.
Pushing is done when you want the image to be sent to a registry which can be accessed easily if authenticated and authorized. To push the image to a registry, use the following command:
docker push registry-name:1.0.0
This will push the registry-name:1.0.0 image to your registry, which is specified by its tag. Make sure the registries in docker build and docker push have the same name.
When not pushing to a registry, one can also create a .tar compressed file which can be uploaded to Portainer to pull the image to your TDC-E device. To do so, type the following command into the terminal.
docker save -o myapp.tar registry-name:1.0.0
This will save the registry that is named registry-name:1.0.0 as myapp.tar. The file is now ready to be transferred.
To provide an image to the Docker container, the image needs to be locally stored on the TDC-E. Two ways of completing this step will be discussed. Firstly, pulling the image from the registry will be described. Secondly, uploading a .tar file to Portainer will be shown.
An easy way to pull the image is logging into the TDC-E, then writing the following line:
docker pull registry-name:1.0.0
This line will pull the docker image from the specified registry onto your TDC-E, which means the program will now be locally stored on your device and ready for execution. Wait until the file is pulled, then proceed to creating a container for the file.
If we created a .tar image, we can use this image to upload it directly to the TDC-E via the Portainer Images sidebar menu. The environment you should be looking at now is shown below:
Select the option Import and select the file that has been created using the previous command.
Wait until the file is uploaded. The file should now be listed in the list of images uploaded to the TDC-E. The image will yet be unused, and a nifty way to check whether creation was successful is by sorting the images by creation date (option Created). Proceed to creating a container for the file.
For the image to be able to run in the Docker environment, a container that the image will be bound to needs to be created. In the next steps, a docker-compose.yml file is created and then described in detail.
To assign the created image to a container, a docker-compose.yml file is created. The structure of the file is as following:
version: "2"
services:
myapp:
image: registry-name:1.0.0
volumes:
- /sys/class/gpio/:/sys/class/gpio/
network_mode: "bridge"
privileged: true
restart: always
Two ways of creating and starting the container are described. The first is done via a direct terminal docker command, while the other allows for uploading the written docker-compose.yml to Portainer.
To create and start a container via terminal, log onto your TDC-E device and create a docker-compose.yml file. Paste the needed code into the file, then stay in the same directory the file is located in. Now type the following command:
docker compose up [OPTIONS] [SERVICE...]
This command builds, creates, and attaches images to containers for the specified services. The container and, by extension, your application, should now start running.
This section describes how to create and start the wanted container via file upload to Portainer.
To add a new stack to the Portainer, select primary and pick the Stacks option. Then select Add Stack. Here you can write your stack in the Web Editor, upload it from your computer or use a git repository to form the docker-compose file. Paste the copied code into the Web Editor.
Additionally, you can add environmental variables and enable access control to restrict the management of this resource to administrators or to a set of users and/or teams. In the example below, the name of the stack is set to myapp and the code has been pasted into the editor.
Once set up, select Deploy the stack to start the upload process. Once the upload is completed, you can click on your stack to view or edit options. With this option, we match the container with the corresponding image specified in it.
The docker-compose.yml in question is the following:
version: "2"
services:
myapp:
image: registry-name:1.0.0
volumes:
- /sys/class/gpio/:/sys/class/gpio/
network_mode: "bridge"
privileged: true
restart: always
Firstly, the docker-compose.yml file specifies the version of the file, which is 2. It's important to note that the Portainer service does not, at the moment, allow .yml versions beyond 2, which is why the latest version has not been specified.
The service that needs to be installed is myapp. For it to run, an image needs to be specified. It takes the previously created registry-name:1.0.0 image, then specifies a volume that will be attached to the container, as GPIO values need to be read. Thus, /sys/class/gpio/ from the host machine is mapped to /sys/class/gpio/ on the container. The network_mode is set to bridge which sets up a communication between the host and the container, isolated from the outside network. Privileges are elevated, and the container is specified to always restart, so the application works continuously.