Create and Upload Your First Docker Image to EdgeXR
Last Modified: 11/15/21
In this tutorial, we will be creating a very simple web server using Docker and NGINX, run it locally and then upload that Docker image of the server to EdgeXR.
By the end of this guide, you should be able to run the Docker Image locally and see a Hello World web page that looks exactly like this: https://reservable10.hamburg-main-tdg.eu.app.tdg.edgexr.org:80/
What Is Docker?
Briefly, Docker is a set of tools that was released in 2013. Docker allows you to easily leverage other applications as images (like we will be doing here with NGINX) and build off them to create your own server-side applications. Your applications can then be built into Docker images by defining instructions needed to setup your applications in a Dockerfile. You can then use the Docker Engine to run any Docker image as a Docker Container of your application.
Another way to frame this is that a Docker Image is the compiled version of your application and a Docker Container is a running instance of the Image.
This provides two key advantages:
Applications can be moved from one Docker environment to another and consistently work.
Applications can easily be scaled up and scaled down to meet real time user demands.
In the context of EdgeXR, this is extremely valuable as it allows your application to easily run and scale across various mobile operator edge infrastructure around the world.
While not the only way to deploy server applications on EdgeXR, Docker is a straightforward way to work with EdgeXR and the recommended approach for developers if possible in production use cases.
Step 0: Install Docker Desktop
If you have not already done so, please install Docker Desktop from the Docker Getting Started page. This will install a suite of tools such as Docker, Docker-Compose, a dashboard to monitor the images and containers on your computer, as well as other advanced tools.
For developers using Windows, EdgeXR at this time only supports Linux based Docker images. Please refer to this documentation that describes how to setup Windows to run Linux based containers: https://docs.docker.com/docker-for-windows/
Once that has been installed, you should be able to open up a terminal and run docker -v, which will print out the version of Docker you just installed.
Step 1: Running Your First Docker Web Server
Let’s start by getting the base version of NGINX up and running. In a command line terminal, type the command:
docker container run --name nginx -p 8080:80 nginx:latest
This command will be running a few different tasks, which might take a minute to complete. Once you see “ready for start up” printed in the terminal, head over to a web browser and type the address “localhost:8080”
You should now see the message Welcome to nginx! Congratulations, in one line you just spun up your first docker web server locally!
Let’s break down the command in a little more detail:
docker container runis the syntax that is used to run a docker image as a container.--name nginxis an optional parameter used to to name our container nginx. If none is provided, a random name will be generated.-p 8080:80is another optional parameter that forwards requests from port 8080 to 80, which is the port NGINX uses. This is convenient for testing in case you have other applications on our computer that may be using port 80. This is the reason why we access NGINX with localhost:8080.nginx:latestis a required parameter that specifies which Docker image to run. This is broken down into the name of the image “nginx”, followed by a colon and then “version number”. “latest” specifies the latest version number that has been published by nginx.
To stop the server, you can do Ctl-C in the Terminal. Alternatively, you can use the Docker Dashboard to stop the container.
Step 2: Creating your First Docker Image
Now that we used the NGINX Docker Image and confirmed it works, we can build a custom web server leveraging it.
Create an empty Dockerfile (no extension) and then add the following :
# use the nginx base image
FROM nginx:latest
# Download a static HTML page and install that as the index.html into our image at the nginx root directory of the server
RUN curl https://reservable10.hamburg-main-tdg.eu.app.tdg.edgexr.org:80/ > /usr/share/nginx/html/index.html
# expose Port 80 for nginx to serve our web page
EXPOSE 80
# optional: start command needed for all docker images to be run when starting a container. in this case, if not included, the nginx base image will call this command
CMD ["nginx", "-g", "daemon off;"]With these instructions, we have leveraged the base image of NGINX and customized it with a simple Hello World HTML page. To see this new HTML page, we need to build these instructions into our own Docker Image.
We can do so by running the following command in the directory that contains our Dockerfile:
docker image build -t helloworld:1.0 .
This will run each instruction step by step from our Dockerfile and build that into an image that we can run just like we did with NGINX.
The
-tparameters allows us to tag ( in others words, name ) the image with an application image name and version number.The
.tells the command which directory to search for the Dockerfile.
Then just like we did with NGINX we can run the image as a container with this command.
docker container run --name helloworld -p 8080:80 helloworld:1.0
To test this, head over to localhost:8080 again in your browser and you should now see this page (if you don’t see this, your browser may have cached the old page, so refresh the page).
Step 3: Uploading Your Docker Image To EdgeXR
For this, you will need an account and organization setup on EdgeXR. If you do not have an account, head over to our Getting Started page. If you have not setup an organization, you can refer to this guide on organizations for how to do so.
Login to the EdgeXR Docker repository using our account username and password. Replace with your EdgeXR account username.
docker login -u <your username> docker.cloud.edgexr.org
Tag your image for use on EdgeXR. For the hello world image we just created, you can use the following. Make sure to replace
<your organization>with your actual organization name you created on EdgeXR.
docker tag helloworld:1.0 docker.cloud.edgexr.org/<your organization>/images/helloworld:1.0
More generically for any Docker image the command is:
docker tag <your application> docker.cloud.edgexr.org/<your organization>/images/<application name>:<version>
Upload this newly tagged image to the EdgeXR repository. Replace
<your organization>the EdgeXR organization name.
docker push docker.cloud.edgexr.org/<your organization>/images/helloworld:1.0
Lastly, we recommend logging out.
docker logout docker.cloud.edgexr.org
Where to Go From Here
Congratulations on uploading your first Docker Image to EdgeXR! Next, we will look at how you can run this uploaded Docker Image as an Application Instance on the EdgeXR Mobile Operator Edge.
If you are interested in deploying our Computer Vision Sample application, you can take a look at our Computer Vision Sample Apps guides.