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).

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).

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:

#
# Base the image on the latest version of Debian
FROM debian:latest

#
# Identify yourself as the image maintainer (where EMAIL is your email address)
LABEL maintainer="EMAIL"

#
# Update apt and update Debian
RUN apt-get update && apt-get upgrade -y

#
# Install NGINX
RUN apt-get install nginx -y

#
# Expose port 80 (or whatever port you need)
EXPOSE 80

#
# Start NGINX within the Container
CMD ["nginx", "-g", "daemon off;"]

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

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).

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

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

Figure 7

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).

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.