Deploy a Container Stack in Portainer from a GitHub Repository – The New Stack

I’ve made no secret that Portainer is my go-to container manager for both standalone Docker instances as well as Docker Swarm. This web-based platform is, by far, the most powerful, flexible, and reliable GUI tool for managing your containerized deployments.

I’ve already introduced you to Portainer, shown you how to deploy a full-stack application, how to create and use volumes, manage secrets, how to add a Kubernetes environment, and even how to deploy the latest release of Portainer.

This time around, I’m going to show you a handy trick that you are sure to add to your Docker container workflow. What we’re going to do is add a Docker compose file to a GitHub repository and then use that repository to deploy a full stack container in Portainer.

In order to pull this off, you’ll need a running instance of Portainer and a GitHub account. Make sure you have those two things up and ready to go before you continue on.

And, without further ado, let’s get down to business.

Preparing Github

The first thing we’ll do is prepare GitHub. There are a couple of things that must be taken care of. Log in to your GitHub account and we’ll add our docker-compose.yml file to a repository. Once you’ve logged in, navigate to the repository you want to use and click Add file > Create new file. We’re going to use a sample WordPress compose file that contains the following content:

Feel free to use the above compose file, modify it to fit your needs, or use your own compose file. Either way you go, once you’re satisfied, make sure to type the necessary commit information and click Commit changes (Figure 1).

Figure 1: Adding our sample WordPress compose file in GitHub.

After saving the file, you’ll need to go back to the root of the repository and click the Code drop-down and then copy the HTTPS link for the repository. This link will be used in Portainer later on.

Before you leave GitHub, you need to create a personal access token, as Portainer cannot authenticate to your GitHub account with standard username/password credentials.

To create the personal access token, click on your GitHub profile image in the top right corner and select Settings from the drop-down menu. On the Settings page, click Developer Settings at the bottom left of the navigation and then click Personal access tokens. On the resulting page (Figure 2), click Generate new token.

Figure 2: Generating a new personal access token in GitHub.

On the resulting page, type a note for the token and then select any necessary scopes you want to add (Figure 3).

Figure 3: Configuring the access token in GitHub.

Once your token is configured, scroll down and click Generate token. You will then be presented with the token, which you’ll need to copy and use in a moment.

So far you have an HTTP link for the repository and a personal access token.

Configuring your Stack in Portainer

Log into Portainer and select the environment you want to work with. Click Stacks in the left navigation and then click Add stack. In the resulting window (Figure 4), give the stack a unique name.

Figure 4: Configuring our new stack that will be pulled from GitHub.

In the Repository URL field, paste the HTTPS link to your GitHub repository. Click the Authentication slider until it’s in the ON position and then type the email address you use to log into GitHub in the Username field. Finally, paste your personal access token in the Personal Access Token field.

You can also enable Automatic Updates by clicking the slider to the ON position and then configuring a fetch interval (the default being 5 minutes). This might be necessary to your project if you regularly update the docker-compose.yml file in your GitHub repository.

By default, this new stack will only be available to Administrators. If you’d rather make it available only to specific users, Restricted (near the bottom), and then select which users you want to give access to the stack. If you forget to do this at first, you can always change the ownership by editing the stack and clicking Change ownership at the bottom of the stack configuration page.

With everything taken care of, click Deploy the stack and wait for the deployment to complete. You should receive no errors and your stack will be listed on the Stacks page (Figure 5).

Figure 5: Our wordpress3 stack has been successfully deployed.

And that, my Docker-loving friends, is all there is to deploying a container stack from a Docker compose file in your GitHub repository. Test this feature out and see if it doesn’t help make your deployments a bit more efficient.

The New Stack is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Docker.

Feature image via Shutterstock.