{"id":297,"date":"2023-09-21T01:32:00","date_gmt":"2023-09-21T01:32:00","guid":{"rendered":"https:\/\/blog.ngocha.biz\/?p=297"},"modified":"2023-09-21T01:32:00","modified_gmt":"2023-09-21T01:32:00","slug":"build-docker-image","status":"publish","type":"post","link":"https:\/\/blog.ngocha.biz\/?p=297","title":{"rendered":"How to Build Docker Image [Comprehensive Beginners Guide]"},"content":{"rendered":"

In this article, you will learn to build a Docker image from scratch and deploy and run your application as a Docker container using Dockerfile<\/code><\/p>\n

As you know Docker is a tool for packaging, deploying, and running applications in lightweight containers<\/a>. If you want to learn about the basics of Docker, refer to the Docker explained<\/a> blog.<\/p>\n

If you don’t have Docker installation, check out the docker installation guide<\/a>.<\/p>\n

Dockerfile Explained<\/h2>\n

The very basic building block of a Docker image is a Dockerfile<\/code><\/p>\n

A Dockerfile<\/code> is a simple text file with instructions and arguments. Docker can build images automatically by reading the instructions given in a Dockerfile<\/code>.<\/p>\n

In a Dockerfile everything on the left is INSTRUCTION<\/strong>, and on the right is an ARGUMENT<\/strong> to those instructions. Remember that the file name is \"Dockerfile\"<\/code> without any extension.<\/p>\n

\"Dockerfile<\/figure>\n

The following table contains the important Dockerfile<\/strong> instructions and their explanation.<\/p>\n

<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Dockerfile Instruction<\/th>\nExplanation<\/th>\n<\/tr>\n<\/thead>\n
FROM<\/td>\nTo specify the base image that can be pulled from a container registry( Docker hub, GCR, Quay, ECR, etc.)<\/td>\n<\/tr>\n
RUN<\/td>\nExecutes commands during the image build process.<\/td>\n<\/tr>\n
ENV <\/td>\nSets environment variables inside the image. It will be available during build time as well as in a running container. If you want to set only build-time variables, use ARG instruction.<\/td>\n<\/tr>\n
COPY<\/td>\nCopies local files and directories to the image<\/td>\n<\/tr>\n
EXPOSE<\/td>\nSpecifies the port to be exposed for the Docker container.<\/td>\n<\/tr>\n
ADD<\/td>\nIt is a more feature-rich version of the COPY instruction. It also allows copying from the URL that is the source and tar file auto-extraction<\/strong> into the image. However, usage of COPY command is recommended over ADD. If you want to download remote files, use curl or get using RUN.<\/td>\n<\/tr>\n
WORKDIR<\/td>\nSets the current working directory. You can reuse this instruction in a Dockerfile to set a different working directory. If you set WORKDIR, instructions like RUN<\/code>, CMD<\/code>, ADD<\/code>, COPY<\/code>, or ENTRYPOINT<\/code> gets executed in that directory.<\/td>\n<\/tr>\n
VOLUME<\/td>\nIt is used to create or mount the volume to the Docker container<\/td>\n<\/tr>\n
USER<\/td>\nSets the user name and UID when running the container. You can use this instruction to set a non-root user of the container.<\/td>\n<\/tr>\n
LABEL<\/td>\nIt is used to specify metadata information of Docker image<\/td>\n<\/tr>\n
ARG<\/td>\nIs used to set build-time variables with key and value. the ARG variables will not be available when the container is running. If you want to persist a variable on a running container, use ENV.<\/td>\n<\/tr>\n
SHELL<\/td>\nThis instruction is used to set shell options and default shell for the RUN, CMD, and ENTRYPOINT instructions that follow it.<\/td>\n<\/tr>\n
CMD<\/td>\nIt is used to execute a command in a running container. There can be only one CMD, if multiple CMDs then it only applies to the last one. It can be overridden<\/strong> from the Docker CLI.<\/td>\n<\/tr>\n
ENTRYPOINT<\/td>\nSpecifies the commands that will execute when the Docker container starts. If you don’t specify any ENTRYPOINT, it defaults to \/bin\/sh -c<\/code>. You can also override ENTRYPOINT<\/strong> using the --entrypoint <\/code>flag using CLI. Please refer CMD vs ENTRYPOINT<\/a> for more information.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/p>\n

Build Docker Image Using Dockerfile<\/h2>\n

In this section, you will learn to build a docker image using a real-world example. We will create an Nginx docker image<\/strong> from scratch with a custom index page<\/strong>.<\/p>\n

The following image shows the high-level workflow of the image build process.<\/p>\n

\"Docker<\/figure>\n

Follow the steps given below to build a docker image.<\/p>\n

\n
Github Repo:<\/strong><\/b> The Dockerfile and configs used for this article is hosted on a Docker image examples Github repo<\/a>. You can clone the repo for reference.<\/div>\n<\/div>\n

Step 1: Create the required Files and folders<\/h3>\n

Create a folder named nginx-image<\/code> and create a folder named files<\/code><\/p>\n

mkdir nginx-image && cd nginx-image\nmkdir files<\/code><\/pre>\n
Create a .dockerignore<\/code> file<\/p>\n
touch .dockerignore<\/code><\/pre>\n
Step 2: Create a sample HTML file and config file<\/h3>\n
When you build a docker image for real-time projects, it contains code or application config files.<\/strong><\/p>\n
For demo purposes, we will create a simple HTML file & config file as our app code and package it using Docker. This is a simple index.html<\/code> file. You can create your own if you want.<\/p>\n
cd into the files folder<\/p>\n
cd files<\/code><\/pre>\n
Create a index.html<\/code> file<\/p>\n
vi index.html<\/code><\/pre>\n
Copy the following contents to the index.html<\/code> and save the file.<\/p>\n
<html>\n  <head>\n    <title>Dockerfile<\/title>\n  <\/head>\n  <body>\n    <div class=\"container\">\n      <h1>My App<\/h1>\n      <h2>This is my first app<\/h2>\n      <p>Hello everyone, This is running via Docker container<\/p>\n    <\/div>\n  <\/body>\n<\/html><\/code><\/pre>\n
Create a file name default<\/p>\n
vi default<\/code><\/pre>\n
Copy the following contents to the default file.<\/p>\n
server {\n    listen 80 default_server;\n    listen [::]:80 default_server;\n    \n    root \/usr\/share\/nginx\/html;\n    index index.html index.htm;\n\n    server_name _;\n    location \/ {\n        try_files $uri $uri\/ =404;\n    }\n}<\/code><\/pre>\n
Step 3: Choose a Base Image<\/h3>\n
We use FROM <\/code>command in the Dockerfile<\/code> which instructs Docker to create an image based on an image that is available on the Docker hub or any container registry configured with Docker. We call it a base image<\/strong>.<\/p>\n
It is similar to how we create Virtual machines on the cloud from a virtual machine image.<\/p>\n
Choosing a base image depends on our application and os platform of choice. In our case, we will pick the ubuntu:18.04<\/code> base image.<\/p>\n
\n
Note:<\/strong><\/b> Always use official\/org approved base images for your applications to avoid potential vulnerabilities. Towards the end, we have added all the public registries that has verified container base images. Also, when it comes to production use cases<\/strong><\/b>, always use a minimal base image like alpine<\/a> (just 5 Mib<\/strong><\/b>) or distroless images.<\/a> Distroless alpine is just 2 MiB<\/strong><\/b><\/div>\n<\/div>\n
Step 3: Create the Dockerfile<\/h3>\n
Create a Dockerfile in the nginx-image<\/code>  folder. <\/p>\n
vi Dockerfile<\/code><\/pre>\n
Here’s the simple Dockerfile<\/code> content for our use case. Add the content to the Dockerfile.<\/p>\n
FROM ubuntu:18.04  \nLABEL maintainer=\"contact@devopscube.com\" \nRUN  apt-get -y update && apt-get -y install nginx\nCOPY files\/default \/etc\/nginx\/sites-available\/default\nCOPY files\/index.html \/usr\/share\/nginx\/html\/index.html\nEXPOSE 80\nCMD [\"\/usr\/sbin\/nginx\", \"-g\", \"daemon off;\"]<\/code><\/pre>\n
Here’s the explanation of each step:<\/p>\n
    \n
  1. With LABEL<\/code> instruction, we are adding metadata about the maintainer. It is not a mandatory instruction.<\/li>\n
  2. FROM<\/code> instruction will pull the Ubuntu 18.04 version Image from the Docker hub.<\/li>\n
  3. In the second line, we’re installing Nginx.<\/li>\n
  4. Then we’re copying the Nginx default config file from the local files<\/code> directory to the target image directory.<\/li>\n
  5. Next, we’re copying our index.html<\/code> file from the local files<\/code> directory into the target image directory. It will overwrite the default index.html<\/strong> file created during the Nginx installation.<\/li>\n
  6. We’re exposing port 80 as the Nginx service listens on port 80.<\/li>\n
  7. At last, we’re running the Nginx server using CMD<\/code> instructions when the Docker image launches.<\/li>\n<\/ol>\n
    For Docker containers,<\/strong> the daemon off;<\/code> directive tells Nginx to stay in the foreground<\/strong>. This means the nginx process will keep running and won’t stop until you stop the container. It disables the self-daemonizing behavior of Nginx. The -g<\/code> option specifies a directive to Nginx.<\/p>\n
    The reason we run the process in the foreground is to attach the console process<\/strong> to standard input, output, and error. Meaning, you can see logs or messages from the Nginx process<\/p>\n
    Step 4: Build your first Docker Image<\/h3>\n
    The final folder & file structure would look like the following.<\/p>\n
    nginx-image\n\u251c\u2500\u2500 Dockerfile\n\u2514\u2500\u2500 files\n    \u251c\u2500\u2500 default\n    \u2514\u2500\u2500 index.html<\/code><\/pre>\n
    Now, we will build our image using the Docker command. The below command will build the image using Dockerfile <\/code>from the same directory.<\/p>\n
    docker build -t nginx:1.0 .<\/p>\n
      \n
    1. -t is for tagging the image.<\/li>\n
    2. nginx<\/code> is the name of the image.<\/li>\n
    3. 1.0<\/code> is the tag name. If you don’t add any tag, it defaults to the tag named latest.<\/li>\n
    4. .  (dot) at the end means, we are referring to the Dockerfile location as the docker build context. That is our current directory.<\/li>\n<\/ol>\n
      \"docker<\/figure>\n
      If the Dockerfile<\/code> is in another folder then you need to specify it explicitly.<\/p>\n
      docker build -t nginx \/path\/to\/folder <\/code><\/pre>\n
      Now, we can list the images by using this command.<\/p>\n
      docker images<\/code><\/pre>\n
      \"docker<\/figure>\n
      We can see the tag is 1.0<\/code> here. If we want to put a specific tag we can put it like this image-name:<tag><\/code>. If you don’t specify any tag, it defaults to latest<\/code> tag.<\/p>\n
      docker build -t nginx:2.0 .<\/code><\/pre>\n
      A single image can have multiple tags. There are two approaches we generally follow to tag the image:<\/p>\n
        \n
      1. Stable Tags<\/strong> – We can continue to pull a specific tag, which continues to get updates. Our tags are always constant, but the image content is changed.<\/li>\n
      2. Unique Tags<\/strong> – We use a different and unique tag for each image. There are different ways to provide unique tags for example date-time stamp, build number, commit ID, etc.<\/li>\n<\/ol>\n
        \n
        Note<\/strong><\/b>: When it comes to production, a recommended docker image tagging method is semantic versioning (Semver)<\/a>.<\/div>\n<\/div>\n
        Docker caches the build steps. So if we build the image again the process will move a little faster. For example, it will not download the Ubuntu 18.04 image again.<\/p>\n
        Using large images slows down the build and deployment time of containers. If you want to learn more about optimizing Docker images, check out reduce docker image<\/a> guide.<\/p>\n
        Step 5: Test the Docker Image<\/h3>\n
        Now after building the image, we will run the Docker image. The command will be<\/p>\n
        docker run -d -p 9090:80 --name webserver nginx:1.0 <\/code><\/pre>\n
        Here,<\/p>\n
          \n
        1. -d<\/code> flag is for running the container in detached mode<\/li>\n
        2. -p<\/code> flag for the port number, the format is local-port:container-port<\/li>\n
        3. --name<\/code> for the container name, webserver in our case<\/li>\n<\/ol>\n
          We can check the container by using the below command<\/p>\n
          docker ps<\/code><\/pre>\n
          \"docker<\/figure>\n
          Now in the browser, if you go to http:\/\/<host-ip>:9090<\/code>, you can see the index page which displays the content in the custom HTML page we added to the docker image.<\/p>\n
          \"valaidating<\/figure>\n
          Push Docker Image To Docker Hub<\/h2>\n
          To push our Docker image to the Docker hub, we need to create an account in the Docker hub<\/a>.<\/p>\n
          Post that, execute the below command to log in from the terminal. It will ask for a username and password. Provide the Docker hub credentials.<\/p>\n
          docker login<\/code><\/pre>\n
          \"docker<\/figure>\n
          After login, we now need to tag our image with the docker username<\/strong> as shown below.<\/p>\n
          docker tag nginx:1.0 <username>\/<image-name>:tag<\/code><\/pre>\n
          For example, here devopscube<\/code> is the dockerhub username.<\/p>\n
           docker tag nginx:1.0 devopscube\/nginx:1.0<\/code><\/pre>\n
          Run docker images<\/code> command again and check the tagged image will be there.<\/p>\n
          \"tagging<\/figure>\n
          Now we can push our images to the Docker hub using the below command.<\/p>\n
          docker push devopscube\/nginx:1.0<\/code><\/pre>\n
          Now you can check this image will be available in your Docker Hub account.<\/p>\n
          \"docker<\/figure>\n
          \"Docker<\/figure>\n
          Using heredoc With Dockerfile<\/h2>\n
          Dockerfile<\/code> also supports heredoc<\/a> syntax. If we have multiple RUN<\/code> commands then we can use heredoc<\/code> syntax as shown below.<\/p>\n
          RUN <<EOF\napt-get update\napt-get upgrade -y\napt-get install -y nginx\nEOF<\/code><\/pre>\n
          Also, let’s say you want to execute a Python script from a Dockerfile, you can use the following syntax.<\/p>\n
          RUN python3 <<EOF\nwith open(\"\/hello\", \"w\") as f:\n    print(\"Hello\", file=f)\n    print(\"World\", file=f)\nEOF<\/code><\/pre>\n
          You can also use the heredoc syntax to create a file. Here is an Nginx example.<\/p>\n
          FROM nginx\n\nCOPY <<EOF \/usr\/share\/nginx\/html\/index.html\n<html>\n  <head>\n    <title>Dockerfile<\/title>\n  <\/head>\n  <body>\n    <div class=\"container\">\n      <h1>My App<\/h1>\n      <h2>This is my first app<\/h2>\n      <p>Hello everyone, This is running via Docker container<\/p>\n    <\/div>\n  <\/body>\n<\/html>\nEOF<\/code><\/pre>\n
          Dockerfile Best Practices<\/h2>\n
          Some of the Dockerfile<\/code> practices that we should follow:<\/p>\n
            \n
          1. Use a .dockerignore<\/code> file to exclude unnecessary files and directories to increase the build\u2019s performance.<\/li>\n
          2. Use trusted base images<\/strong> only and keep updating the images periodically.<\/li>\n
          3. Each instruction in the Dockerfile<\/code> adds an extra layer to the Docker image. Minimize the number of layers by consolidating the instructions to increase the build\u2019s performance and time.<\/li>\n
          4. Run as a Non-Root User<\/strong> to avoid security breaches.<\/li>\n
          5. Keep the image small:<\/strong> Reduce the image size for faster deployment and avoid installing unnecessary tools in your image. Use minimal images to reduce the attack surface.<\/li>\n
          6. Use specific tags over the latest tag for the image to avoid breaking changes over time.<\/li>\n
          7. Avoid using multiple RUN<\/code> commands as it creates multiple cacheable layers which will affect the efficiency of the build process.<\/li>\n
          8. Never share or copy the application credentials or any sensitive information in the Dockerfile<\/code>. If you use it, add it to .dockerignore<\/code><\/li>\n
          9. Use EXPOSE <\/code>and ENV<\/code> commands as late as possible in Dockerfile<\/code>.<\/li>\n
          10. Use a linter: <\/strong>Use a linter like hadolint<\/a> to check your Dockerfile for common issues and best practices.<\/li>\n
          11. Use a single process per container:<\/strong> Each container should run a single process. This makes it easier to manage and monitor containers and helps to keep containers lightweight.<\/li>\n
          12. Use multi-stage builds:<\/strong> Use multi-stage builds to create smaller and more efficient images.<\/li>\n<\/ol>\n
            Possible Docker Build Issues<\/h2>\n
              \n
            1. If there is a syntax error or an invalid argument in Dockerfile,<\/code> docker build <\/code>command will fail with an error message. Correct the syntax to resolve this.<\/li>\n
            2. Always try to give the container name using docker run <\/code>command otherwise Docker automatically assigns a name to the container and it might lead to several problems.<\/li>\n
            3. Sometimes we get Bind for 0.0.0.0.:8080 failed: port is already allocated<\/strong> error, this is because some other software\/service is using these ports. We can check the listening ports using netstat<\/code> or ss<\/code> command. Use a different port to resolve this or stop that service.<\/li>\n
            4. Sometimes Docker fails to download the packages with this error Failed to download package <package-name><\/strong>. This is because the container may not be able to access the internet or other dependencies issues.<\/li>\n<\/ol>\n
              Docker Image Registries<\/h2>\n
              As mentioned in Step 1, you should always choose verified official base images for your application.<\/p>\n
              The following table has the list of publicly available container registries where you can find officially verified base images and application images.<\/p>\n
              <\/p>\n\n\n\n\n\n\n\n\n
              Registry<\/th>\nBase Images<\/th>\n<\/tr>\n<\/thead>\n
              Docker<\/td>\nDocker hub base images<\/a><\/td>\n<\/tr>\n
              Google Cloud<\/td>\nDistroless base images<\/a><\/td>\n<\/tr>\n
              AWS<\/td>\nECR public registry<\/a><\/td>\n<\/tr>\n
              Redhat Quay<\/td>\nQuay Registry<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
              <\/p>\n
              Docker Image vs. Containers<\/h2>\n
              A Docker image is a snapshot of the file system and application dependencies. It is an executable package of software that includes everything needed like application code, libraries, tools, dependencies, and other files to run an application. You can compare it to a VM golden image.<\/strong><\/p>\n
              A Docker image is organized in read-only layers stacked on top of each other.<\/p>\n
              A Docker container is a running instance of a Docker image. We create VMs from VM images. Similarly way we create a container from a container image. When you create a container from a Docker image, you are creating a writable layer on top of the existing image layers.<\/p>\n
              The key difference between a Docker image and a container is the writable layer on top of the image. This means, that if you have five containers running from an image, all the containers share the same read-only layers from the image and only the top writable layer is different for all five containers.<\/p>\n
              This means, that when you delete the container, the writable layer gets deleted.<\/p>\n
              Images can exist without containers, whereas a container needs an image to run. We can create multiple containers from the same image, each with its own unique data and state.<\/p>\n
              \"Docker<\/figure>\n
              Docker Image Build FAQs<\/h2>\n
              Following are the frequently asked questions regarding docker image build<\/a>.<\/p>\n
              How to use base images from container registries other than Docker hub?<\/h3>\n
              By default docker, the docker engine is configured with the docker hub container registry. So if you mention the image name, it pulls the image from the docker hub. However, if you want to use an image from a different container registry, you need to provide the full URL of the image. For example, FROM gcr.io\/distroless\/static-debian11<\/code><\/p>\n
              What is Docker build context?<\/h3>\n
              Docker build context<\/strong> is the docker host location where all the code, files, configs, and Dockerfile are present during the docker build process. You can specify the current build context using a dot [.] or the path of the folder. Also, you can have the Dockerfile in a different location than the build context. As a best practice, always have only the required files in the build context. Or else you will have unwanted files and a bloated Docker image.<\/p>\n
              How to build a Docker Image from a git repository?<\/h3>\n
              You can use the docker build command with a git repository to build a docker image. The git repository should have the Dockerfile and required files for a successful image build.<\/p>\n
              Whats Next<\/h2>\n
              In the same way, you can try building more Docker images.<\/p>\n
              For example, you can try Dockerizing a Java application<\/a> and run it.<\/p>\n
              Further you can dockerize the following applictions to gain more knowledge.<\/p>\n
                \n
              1. Python<\/li>\n
              2. NodeJS<\/li>\n
              3. Django<\/li>\n
              4. FastAPI<\/li>\n<\/ol>\n
                Conclusion<\/h2>\n
                In this article, we discussed how we can build a Docker Image<\/strong> and run our app as a Docker container using a Dockerfile<\/code>.<\/p>\n
                We discussed  Dockerfile<\/code> in detail and went through some good practices to write it.<\/p>\n
                As a DevOps engineer<\/a>, it is important to have a solid understanding of Docker best practices before implementing them in a project. Additionally, to learn Kubernetes<\/a>, you need to understand the workflow of building container images.<\/p>\n
                Podman is another container tool using which you can manage containers. To know more, check out the podman tutorial.<\/a><\/p>\n
                Ready for a real-world advanced use case? <\/p>\n
                Learn about deploying LLaMA models with Docker and vLLM<\/a> for GPU inference.<\/p>\n
                \n
                Ngu\u1ed3n:<\/strong> How to Build Docker Image [Comprehensive Beginners Guide] \u2014 DevOpsCube<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
                Source: https:\/\/devopscube.com\/build-docker-image\/<\/p>\n","protected":false},"author":1,"featured_media":298,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-297","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops"],"_links":{"self":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/297","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=297"}],"version-history":[{"count":0,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/297\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/media\/298"}],"wp:attachment":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=297"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=297"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=297"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}