TutorialsLast Updated Nov 3, 202610 min read

Azure Container Registry: Continuously deploy custom images with CircleCI

Fikayo Adepoju

Fullstack Developer and Tech Author

Azure Container Registry (ACR) is Microsoft’s own hosting platform for Docker images. It is a private registry where you can store and manage private docker container images and other related artifacts. These images can then be pulled and run locally or used for container-based deployments to hosting platforms.

In this tutorial, you will learn how to create a custom docker image and continuously deploy it to an Azure container registry.

Prerequisites

To follow this tutorial, a few things are required:

  1. Node.js installed on your system (version 24 or later)
  2. An Azure account. Azure Container Registry task runs, which this tutorial uses for az acr build and the build task, are temporarily paused for subscriptions on Azure free credits, so use a subscription that doesn’t rely on free credits.
  3. A CircleCI account
  4. A GitHub account
  5. Azure CLI installed on your system
  6. Docker installed on your system

With all these installed and set up, you can begin the tutorial.

Creating a container registry on Azure

To begin, you need to create a container registry on Azure to store and build your Docker containers. Select Create a resource on your Azure portal home page and go to Infrastructure Services -> Container Registry -> Create.

The Azure portal Create a resource page with the Infrastructure Services category selected and the Container Registry tile showing its Create link.

On the registry creation page, fill in the appropriate information including the name for your registry.

The Basics tab of Create container registry with the Demos-Group resource group, the circlecigwpregistry registry name, the East US location, and the Standard pricing plan.

Click the Review + create button. On the review page, confirm your registry information and click Create to trigger the registry creation process.

If you prefer using the Azure CLI to create your resources, you can also use this command to create the registry:

az acr create --name circlecigwpregistry --resource-group Demos-Group --sku standard --admin-enabled true

Note that I have named my registry circlecigwpregistry in this process. Registry names must be unique across Azure, so you’ll need to use a different name. Be sure to substitute your registry name in all the steps in this tutorial going forward.

Cloning the demo project

The next step is to get the Node.js project that will be used to build a Docker container and host it in the Azure container registry. Run the following command to clone the project:

git clone --single-branch --branch base-project https://github.com/CIRCLECI-GWP/azure-custom-images.git

This project is a basic Node.js API with two endpoints:

  • The root endpoint (/) simply prints out a welcome message
  • The /todos endpoint returns an array of todo task objects, and also contains a test suite for testing the /todos endpoint

Writing and building the custom Docker image

The next step is to write a custom Docker image to host the application in. Go into the root of the project folder (cd azure-custom-images) and create the Dockerfile file. Input the following code into the file:

FROM node:24-alpine

WORKDIR /app

COPY ./package.json ./

RUN npm install

COPY ./ ./

CMD ["npm", "start"]

The Dockerfile uses node:24-alpine as its base image and sets the working directory in the container (that is to be created based on this image) to /app. The package.json file is first pulled into /app to install dependencies using npm install. Lastly, the remaining contents of the project are copied into the image and the application will be started using npm start at runtime. Refer to this page for more context about Docker images and containers.

Build the image by running the following command at the root of the project and tagging it with the name customnodeimage.

docker build -t customnodeimage .

Note the dot (.) at the end of the command. Do not forget to add this; it defines the build context to be the current directory.

Once built, you can then run the following command to run the Node.js application as a container based on the customnodeimage Docker image.

docker run -p 1337:1337 customnodeimage

The output of that command in your CLI should contain the line Server running on localhost:1337, which indicates that the application is running.

The previous command forwards the application port in the container (1337) to port 1337 on your machine. You can navigate to http://localhost:1337 to view the application base endpoint.

The todos API running locally at localhost:1337 in Chrome, showing the message "Welcome to the 'todos' API".

You can also visit the /todos route to load the todo objects.

The /todos endpoint at localhost:1337 in Chrome, returning a JSON array of three todo items.

To get this image to your registry, run the following command to build the image on ACR from the Dockerfile. Replace <container_registry_name> with the name you gave the registry you created.

az acr build --registry <container_registry_name> --image customnodeimage .

You can now view this image on your registry. Click your registry on the Azure resources page. It should be listed under Recent resources on the Azure portal home page. Go to Services -> Repositories.

The Repositories page of the circlecigwpregistry registry in the Azure portal, listing the customnodeimage repository.

Setting up a build task for the container

When any update is made to the application code or the Dockerfile, we want the updates pushed and built on ACR, so that there is always an updated image on ACR. That is continuous deployment.

Fortunately, ACR can be configured to watch a branch on a remote repository and trigger builds based on updates to that branch. The strategy for continuous deployment of the image is to create a branch on the remote repository for the image that ACR will watch to trigger builds. Once the application tests pass, updates are then automatically pushed to the watched branch to trigger a rebuild of the image using the updated content.

To begin, run the command rm -rf .git at the root of the project to remove any existing git history, then push the project to GitHub.

Next, on the GitHub repository, create a buildimage branch from the main branch.

The GitHub branch menu with buildimage typed in the filter and the option to create branch buildimage from main.

To watch the branch just created, you will need an ACR task. To create an ACR task, you will need a GitHub personal access token.

To create a GitHub token, go to Settings -> Developer settings on your GitHub page. On the side menu, click Personal access tokens -> Tokens (classic), then click Generate new token -> Generate new token (classic). If GitHub asks for access confirmation, confirm it to continue to the token creation page.

In the Note field, describe what the token is for. For this demo, give it the full repo scope. That scope includes access to the repository’s webhooks, which matters most here: ACR uses it to create a webhook in the repo that will signal ACR to trigger a new build of the Docker image. For a public repository, the repo:status and public_repo scopes are enough. Pick an Expiration that covers how long the demo will run. The ACR task uses this token to access the repository, so after it expires, give the task a new one with az acr task update --git-access-token.

The GitHub New personal access token (classic) page with a note, a 7-day expiration, and the repo scope selected.

Click the Generate token button. Copy the token once it is generated. It will not be displayed again.

To create an ACR task, run the following command at the root of your project using your repository address, your registry name, and GitHub access token:

az acr task create --registry <container_registry_name> --name buildcustomimage --image customnodeimage --context <your_github_repo>#buildimage --file Dockerfile --git-access-token <access_token>

For the registry and repository in this tutorial, that will be:

az acr task create --registry circlecigwpregistry --name buildcustomimage --image customnodeimage --context https://github.com/CIRCLECI-GWP/azure-custom-images.git#buildimage --file Dockerfile --git-access-token [My_TOKEN]

This will create a buildcustomimage task that will rebuild the customnodeimage image each time updates are pushed to the buildimage branch. To view your newly created task, go to the registry page and go to Services -> Tasks.

The Tasks tab of the circlecigwpregistry registry, listing the buildcustomimage task on the linux platform with its trigger icons.

Creating the CircleCI project

The CircleCI steps in this tutorial assume a github organization, which CircleCI creates when a user signs in with GitHub. Organizations of the circleci type connect through the CircleCI GitHub App, set up projects differently, and don’t support user keys; see Create a project.

Now, go to the Projects page on the CircleCI dashboard. Make sure the organization for the GitHub account used in this tutorial is selected, then find the repository in the list.

The CircleCI Projects page filtered to the azure-custom-images repository, with its Set up button.

Click Set up next to the repository to begin adding information.

The CircleCI "Select your config.yml file" dialog with the Faster option selected and the Set Up Project button.

In the modal that opens, select Faster to commit a starter pipeline to a new circleci-project-setup branch, then click Set Up Project. We’ll add this project’s own configuration to the main branch later in this tutorial; the circleci-project-setup branch can be deleted after that.

Setting up GitHub authentication

Part of the continuous deployment strategy is to make a push to the buildimage branch from the pipeline configuration that will be written for this project, thus authenticated access is required for CircleCI to access the repository on GitHub.

Fortunately, CircleCI provides a way to add a user key to achieve that. On your project, go to Project Settings -> SSH Keys and go to the User Key section. If the section shows an Authorize with GitHub link, click it to make a connection to GitHub, then return to the User Key section on the SSH Keys page.

Click Add User Key, then click Confirm User when CircleCI shows its warning about using a machine user.

The CircleCI "Confirm this user is a machine user" dialog with the Confirm User button, opened from the Add User Key button on the SSH Keys page.

CircleCI now uses this key to check out the code, which gives the pipeline the write access it needs to push to the buildimage branch.

Because the pipeline script uses the GitHub email and username, store them as environment variables. On the side menu of your project settings click Environment Variables and add these:

  • GITHUB_EMAIL is the email of your connected GitHub account
  • GITHUB_USERNAME is your GitHub username

Writing the pipeline script

The final task in this tutorial is to write the continuous deployment pipeline script for the custom docker image.

To enable the pipeline script to push updates to the buildimage branch of the GitHub repo, we will use the node package gh-pages. This package is configurable for pushing files from one branch to another in any given repository.

Install the package as a development dependency using the following command at the root of the project:

npm install gh-pages --save-dev

Next, add a pushtobuild script in the package.json file:

"scripts" : {
  .....,
  "pushtobuild": "npx gh-pages -b buildimage --message '[skip ci] Updates' -d ./"
}

This script invokes gh-pages using npx to push files from the main branch to the buildimage branch. The --message parameter of [skip ci] Updates is added so that CircleCI does not re-run the pipeline when changes are pushed to this branch.

Now you can begin writing the pipeline script. At the root of your project, create a folder named .circleci and inside it, a file named config.yml. Inside config.yml, enter:

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: install-packages
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules
      - run:
          name: Run tests
          command: npm run test

  deploy:
    working_directory: ~/repo
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - run:
          name: Configure Github credentials
          command: |
            git config user.email $GITHUB_EMAIL
            git config user.name $GITHUB_USERNAME
      - run:
          name: Build Image on Azure Container Registry Task
          command: npm run pushtobuild

workflows:
  build:
    jobs:
      - build
      - deploy:
          requires:
            - build # only deploy once build job has completed
          filters:
            branches:
              only: main # only deploy on the main branch

This file defines a workflow with two jobs.

The build job checks out the code from the remote repository, installs required dependencies, and runs the tests to ensure that no bugs are contained in the code. Once the build job is complete, the deploy job takes over and checks out a clean copy of the code (we do not want to push the node_modules folder from the previous job to the watched branch). It then sets the Git user email and name that the pipeline script uses for the commits it pushes to the watched branch (buildimage). Finally, the deploy job runs the Node.js script to push updates and trigger a new build of the docker image.

When you commit your updates and push to the GitHub repository, you will have a successful workflow!

The CircleCI workflow page for a push to main, with the build workflow successful and its build and deploy jobs both green.

You can click on the build job to view the successful tests.

The CircleCI build job with the Run tests step expanded, showing the apiTest.js suite passing its Fetch Todos test.

To see the details of the process, click the deploy job (in your browser, go back one page).

The CircleCI deploy job with the Build Image on Azure Container Registry Task step expanded, showing gh-pages publishing to the buildimage branch.

Go to your registry task at Services -> Tasks and click the Runs tab. You will see the build running.

The Runs tab of the circlecigwpregistry registry, showing a buildcustomimage run triggered by a commit with the status Running.

After a while, the build will be complete and marked as Succeeded.

When you go to your image at Services -> Repositories and click the image, you will notice that the Last updated date has changed, indicating that the new build is now the most recent.

Conclusion

Azure Container Registry gives you the ability to store your container images, enabling fast and scalable retrieval of container workloads. In this tutorial, you have built a custom docker image and continuously deployed it to ACR each time your application code or Dockerfile changes. To get started applying what you have learned to your own work, sign up for your CircleCI free trial today.

Happy coding!


Fikayo Adepoju is a LinkedIn Learning (Lynda.com) Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.