How to Build and Publish a Docker Image to Azure Container Registry

Step-by-Step instructions on creating and deploying a Docker Image to Microsoft Azure Container Registry.
8 min read
May 1, 2024
How to Build and Publish a Docker Image to Azure Container Registry

Table of Content

Share this


Docker has revolutionized the software industry with its platform that miniaturizes the deployment of applications in lightweight containers. One organization that’s leveraging Docker’s capabilities is Microsoft through its Azure Container Registry (ACR), and in this article, we’ll guide you through the process of building and publishing a Docker image to the ACR.

Basics of Docker and Azure Container Registry

Docker is an influential open-source technology that allows developers to build, run, and share applications securely within the lightweight, standalone packaging of containers. It breathes life into the concept of containerization, which encapsulates software in a manner that is portable and predictable during application deployment.

Azure Container Registry, on the other hand, is a managed Docker registry service hosted on Microsoft’s reputable Azure Cloud Platform. This service caters to storing and managing private Docker container images, providing users with a centralized approach to container image storage. It works in close vicinity with the existing container development and deployment pipelines.

Getting Ready – Prerequisites

Before diving into the detailed process of building and uploading a Docker image to Azure Container Registry, it’s crucial to ensure that you have the necessary tools and access in place. Here are the prerequisites for this guide:

  1. Docker: The Docker engine is required for creating Docker images. If you haven’t installed Docker yet, you can download it from the Docker website. Make sure that you’re using the latest version for optimal performance.
  2. Azure Account: You’ll need an active Azure account to use the Azure Container Registry. If you don’t have one, you can create one for free.
  3. Azure CLI: Azure Command-Line Interface, often termed as Azure CLI, is a set of commands used to create and manage Azure resources. Installing Azure CLI on your local machine would help in easily navigating through Azure services.
  4. Text Editor (Optional): While not 100% necessary, a text editor like Sublime Text, Notepad++, or VS Code, can be useful when putting together your Dockerfile.

Building your Docker Image: Step-by-Step Guide

With everything set up and ready, you can now venture into the process of creating a Docker image. If you are new to Dockerfiles, I highly recommend reading this article to get more insights into how Dockerfiles work. Here’s the step-by-step process:

Step 1: Creating the Dockerfile

A Dockerfile is a text document that contains all the commands a user could call on the command line to build an image. Create a new file in your preferred text editor and save it as Dockerfile (with no extension).

Step 2: Writing the Dockerfile

Dockerfile uses specific syntax to control the Docker image’s build process. Inside this file, you define your base image, specify your application’s requirements, and configure the runtime. For example, you might label your Docker image, set environment variables, or specify a run command.

Sample Dockerfile for a simple Node.js web application:

# Using the official lightweight Node.js base image
FROM node:14-alpine
# Set the working directory in the Docker container
# Copy the package.json file from your local directory to the working directory in Docker
COPY package*.json ./
# Running npm install command within Docker to install all dependencies
RUN npm install
# Copying the rest of your code into Docker 
COPY . .
# Setting the port for the application
# At the end, running the node server
CMD ["node", "server.js"]

The sample application used here is available on my GitHub repo.

Step 3: Building the Docker Image

Now that your Dockerfile is set up, navigate to the directory containing the Dockerfile in your command line or terminal. Run the docker build command followed by a tag for the image, and a dot (.) to specify the current directory:

docker build -t my-app:1.0 .

This command will create a Docker image named ‘my-app’ and tag it as ‘1.0’. Docker reads your Dockerfile, processes the commands in order, and creates a new Docker image.

Creating an Azure Container Registry

Creating an Azure Container Registry is synonymous with making a dedicated and secure private space on Azure for your Docker images. This platform boasts compatibility with major Docker command-line interface and Docker Orchestration tools. Let’s explore the sequential step-by-step process of creating an Azure Container Registry:

  • Navigate to the Azure portal at and enter your credentials.
  • Identify the Azure’s left-hand navigation pane and select Create a Resource.

    Azure Create a new resource
    Create a new resource
  • A window with the title New should pop up. Look for the search bar and type Container Registry. You should see an option by Microsoft. Click on it.

    Search Container Registry
    Search Container Registry
  • Click on the Create button on the bottom left of this page to begin creating your Container Registry.

    Create Container Registry
    Create Container Registry
  • Fill out the necessary details, including but not limited to:
    • Registry name: Choose a name that is unique across Azure and is used as the hostname within your Docker commands.
    • Subscription: Choose the one of existing subscription that you have.
    • Resource group: You may choose an existing resource group or create a new one.
    • Location: Choose the location of your choice.
    • SKU: It represents the tier and capabilities of the registry. Select Basic for now.
    Create Container Registry
    Create Container Registry

    Review the information you filled in. Click on Review + Create once you are satisfied with your inputs.

  • One last review and check of your settings! If everything looks perfect, select Create to kickstart the deployment of the container registry.

    Review Container Registry
    Review Container Registry
  • Click Go to resource once the deployment is complete.

    Go to resource
    Go to resource

Pushing Docker Image to Azure Container Registry

With a built Docker Image and an Azure Container Registry at your disposal, the stage is set to push your Docker image to Azure Container Registry for secure and reliable management. Let’s delve into the details:

  • Authentication with Azure Container Registry: Before anything else, you need to get authenticated with Azure CLI. Use the below az acr login command to login as an admin. Replace ‘MyRegistry’ with the name of your registry:
az acr login --name MyRegistry
Azure CLI Docker Login
Azure CLI Docker Login
  • Pillars of Docker Images: Tags: Docker images must bear a tag with the Azure Container Registry’s login server name. This adds a layer of control and traceability to your workflow. Tag your Docker images as follows:
    Replace my-app:1.0, which is the Docker image name and its tag, and {MyRegistry}, the fully qualified name of the image on Azure. If you have a docker extension in VS Code, you will see the new image and tag alongside in the extension view.
docker tag my-app:1.0
Azure CLI Docker Tag
Azure CLI Docker Tag
  • The Push Command: Time to finally push your Docker image into Azure Container Registry. Execute the command given below. Again, remember to put the name of your registry and your image name in
docker push
Docker ACR Push
Docker ACR Push

Troubleshooting Common Errors

When working with Docker Images and Azure Container Registry, you might encounter some common errors. Here’s a guide on troubleshooting those:

  • Error: ‘Docker not recognized as an internal or external command’
    • This usually means Docker isn’t installed on your machine. Make sure you have correctly installed Docker and added it to your PATH.
  • Error: ‘Cannot connect to the Docker daemon’
    • This error suggests that Docker is not running. You can start Docker by opening the Docker Desktop application or by using the Docker service start command.
  • Error: ‘Authentication failed with Azure Container Registry’
    • This indicates that the login process with Azure CLI failed. Double-check your Azure credentials and try again.
  • Error: ‘Tag not found’
    • This error means that the Docker image with the provided tag doesn’t exist in your local Docker environment. Verify the Docker images and their tags by using the Docker images command.
  • Error: ‘Docker push to Azure Container Registry failed’
    • This error suggests a failed push operation. This could be due to issues like network failure, incorrect registry name, or tag. Confirm that the Docker image tag and the Azure Container Registry name are correct.


Docker’s strength in creating lightweight, individual containers interfaces powerfully with Microsoft Azure’s robust cloud services, resulting in a synergistic relationship. Docker simplifies application deployment, while Azure, with its dedicated and secure Azure Container Registry, offers a storage and management solution for Docker images that’s easy to fit into your workflow.

Stay wired with our newsletter!

Recommended Articles

Stay Up To Date with
Cloud News and Tutorials!

Subscribe to our weekly newsletter!

By entering your email address, you agree to our privacy policy.