Modal Title
Cloud Native Ecosystem / Containers

Build and Use a Custom Image with Portainer

Stuck on the difficulties of creating container images? This tutorial walks you through how to create a local image registry, built a custom image, and deploy a container from that image — all with Portainer.
Apr 8th, 2023 6:00am by
Featued image for: Build and Use a Custom Image with Portainer

Have you ever tried to deploy a local Docker registry, build a Docker image, push the image to that local registry, and use the image for a new container deployment? If you have, you know how challenging and time-consuming that task can be. Get one thing wrong and nothing will work. I’ve done it enough to know that it’s not always guaranteed to work as expected.

But what if there was a much easier route? Wouldn’t it make sense to take the path that is not only more efficient but is almost a sure thing to work exactly as expected… every time?

The answer to that is a resounding yes.

To that end, the other day I set out to see just how easy that process would be with my favorite container management platform, Portainer. I was shocked at how simple it is. Now, there are a few “moving parts” you have to take care of, but it’s far fewer than doing it the old fashion command line way and it’s also more reliable. On top of all that, it’s done entirely through the web-based GUI, so it’s not just easier, it’s far more efficient.

I’m going to show you how it’s done.

What You’ll Need

The only thing you’ll need for this is a running instance of Portainer. That’s it. Let’s make it happen.

How to Create a Custom Registry

The first thing we have to do is create a custom registry. Fortunately, Portainer has everything needed for this, built right in. So, to create the new registry, log into Portainer, and select your Docker environment, and then click Applications in the left navigation. Select the first entry, titled Registry. Give the new registry a name and click Deploy the container.

Next, click Environments in the left navigation and click Add Environment. Select Docker Standalone and then click Start Wizard. In the resulting window (Figure 1), select API, give the new registry a name, and then, for Environment Address, type SERVER:5000 (where SERVER is the IP address of the hosting server).

Creating a new Environment in Portainer.

After completing the Wizard, click Connect and your new registry is ready to go. Make to then go to Registries (in the left navigation), click Add Registry, select Custom Registry, give the registry a name, and use SERVER:5000 (where SERVER is the IP address of the hosting machine),. and click Add Registry.

How to Build a Custom Image

The next step is building a custom image. We’re going to build an image using Debian and NGINX. To do that, click Images in the left navigation and then click Build a New Image (Figure 2).

Figure 2: Building a new image with Portainer is fairly straightforward.

On the next page (Figure 3), give the new image a name (such as debian:apache), click Web Editor, and then paste the following into the editor pane:

Figure 3: Our custom image is ready to build.

Scroll down and click Build Image. It’ll take 2-5 minutes to complete the build process. When finished, click Images again in the left navigation and locate the newly built image with the name you gave it.

Tag the New Image

To make the image available to the custom registry, you must tag it as such. Remember, our custom registry URL is SERVER:5000 (where SERVER is the IP address of our registry), which is what we’ll use in the tagging process. Go back to Images and locate the newly built image. It should be listed with a tag from the name you gave the custom image (Figure 4). In my case, that was debian:nginx.

Figure 4

Our custom image was successfully built and is ready to tag.

Click the image ID (the blue random string of characters). In the resulting window, make sure to select the custom registry you created from the Registry drop-down (mine is named hive) and then type the name of the custom image you created. You should also see SERVER:5000 (where SERVER is the IP address of your hosting server) to the left of the image name (Figure 5).

Figure 5: We’re tagging our new image.

Click Tag and the image will now be available to our custom registry.

Deploy a Container with Our New Image

Click Containers in the left navigation and Add Container. In the resulting window (Figure 6), give the container a name, select your custom registry from the Registry drop-down, type the name of the image to use (in my case, debian:nginx), add a custom port mapping of something like 8888 for the local port and 80 for the container port, and click Deploy The Container.

Figure 6

Deploying a new container using our custom image from our custom registry.

You should be automatically redirected back to the container list where you’ll see the new container is running (Figure 7).

Figure 7

Our new container is up and running.

Point a web browser to http://SERVER:PORT (where SERVER is the IP address of your hosting server and PORT is the local port you used when configuring the container deployment. You should see the NGINX Welcome screen (Figure 9).

Figure 9: NGINX is serving up web pages.

Congratulations, you’ve successfully created a local image registry, built a custom image, and deployed a container from that image. Thanks to Portainer, this process is considerably easier than doing so from the command line.

Group Created with Sketch.
TNS owner Insight Partners is an investor in: Docker.
THE NEW STACK UPDATE A newsletter digest of the week’s most important stories & analyses.