What is Portainer?
Portainer is a lightweight management UI that allows you to easily manage your Docker host or Kubernetes Clusters. Portainer is as simple to deploy as it is to use.
It allows anyone to deploy and manage containers without the need to write code.
Portainer can be used to set up and manage an environment, deploy applications, monitor application performance, and spot problems easily.
Portainer, as a whole, is a self-hostable, open-source, container management system. Giving you complete visual control over your Docker instances. With Image management, restart policies and usage logs.
Require some assistance?Our experts can help get you set up!
Find out more
Prerequisites: Provisioning your server
You'll need to either purchase something like a Raspberry Pi or use an existing server at your disposal.
I use a Proxmox instance running on a server in my loft.
Step 1: Installing Docker on your server
All of the following instructions are based on the Debian distro, so if you're running a server with Ubuntu, these instructions will be perfect for you. If not, you may have to adjust the commands below to suit your distro.
The first step is to just make sure our server is up to date. Run the following commands to pull down the latest updates from our distro repositories.
sudo apt-get update && sudo apt-get upgrade
You should see an output like the following
Next, we need to install Docker. Docker is the layer which your containers run. Portainer is a UI that sits upon Docker to assist with container management.
To install Docker on your instance, you need to run the following command.
The following script is a convenience script provided by the Docker team. It's highly recommended to always check what you're going to execute, before executing it.
Once you have executed the Docker install script. You should see an output like the following.
As you can see in the output, the command was executed successfully. You may also notice that there is a console message specifying how to use Docker as a non-root user.
This means that whenever you are executing the Docker command, you'll no longer need to type in your sudo password.
If this sounds good to you, you can simply run the provided command, substituting
your-user for your server user. In my case, my user is
ubuntu. My command would look like this.
Step 2: Installing Portainer
It's now time to install Portainer on our Ubuntu instance.
The first step to installing Portainer is to create a persistent volume within Docker.
This means that whenever we shut down our Docker container or reboot our server. All the data associated with Portainer is persisted. Meaning it'll save our data and spin back up.
To do this, we need to execute the following command.
Your output will simply be the following.
Next, we just need to run the Docker command to pull down the latest Portainer image and spin up our container.
If you're new to Docker, this command may look quite confusing to you. Which is part of the business model of Portainer. Portainer takes the complications out of spinning up Docker containers.
The following command configures:
- The mode in which the Docker command will run in (detached)
- The port/s specified to run the container on (8000 and 9000)
- The name of the container (Portainer)
- The restart policy (Whether or not to spin the container back up if we restart or manually stop the service)
- The mount points for the Container and our host machine
- And finally the image we are going to use to run our Container (portainer/portainer-ce)
All of this is a single command, confusing right?
Anyway, let's execute the command to spin up Portainer.
Because we're running in detached mode, we can't see much output other than a Container hash.
To see some more detail, let's run a command to show all of our running Docker containers.
Here we can see that our Container has started correctly, and is running on the ports that we configured.
Let's now go to our browser and log in to Portainer using the GUI.
To navigate to Portainer, you need to enter your servers' IP address into the URL bar of your web browser. Followed by
In my case, my server is running on
So I would type in
Once you have hit the Portainer configuration screen, you should be able to enter a Username and Password. Once done, click
Next, you'll see a screen that looks like the following.
By default, Kubernetes is selected. Kubernetes is something for another blog post. For now, we're going to select Docker.
We can now hit
Once done, you should be able to see the following screen.
Congratulations, Portainer is installed!
Let's take a look around
So, first off. Let's dive into our local endpoint (you can configure remote Docker instances to manage with Portainer).
Click on the box with
This will take you to the Endpoint summary for your endpoint.
As you can see, we have 1 Container, 1 Image and 1 Volume already running. Can you guess why?
That's right! (probably), Portainer is showing us the Portainer Docker instance which is running on our machine. This is because Portainer is just a fancy wrapper around the Docker service.
Creating a new container
We've recently posted about how to self-host PiHole, so I figured it would be a good idea to show you how to set up PiHole via Portainer.
Firstly, let's create a new container by clicking the button on the top row.
You'll be greeted with the Create container dashboard.
Let's start with a name that we want to give our Container. As I mentioned before, I'm going to be using PiHole as our example.
I'm going to call mine PiHole.
Next, we need to find the PiHole image from the DockerHub registry. Navigate to https://hub.docker.com/ and search for PiHole. You should come across the following page.
Near the top, you'll see
pihole/pihole. This is our image name. Take a copy and switch back to the Portainer screen.
Paste in the image name and scroll down to the
Network ports configuration.
We need to publish some ports according to the PiHole documentation. Don't worry, this isn't exposing to the internet. When a Docker container is running, it's almost like a black box, where nothing can get in or out unless we explicitly allow it to. So when we expose ports, we're allowing our host machine the ability to communicate with the Docker Container.
Flipping back to the DockerHub page, we can see some port requirements for PiHole
We need to add each one of these ports to our Portainer config. The left-hand side of the colon
: is our host machine port. The right-hand side is the port that the Docker Container is running this service on. We are mapping our port, to the container port.
Once you've added your ports in Portainer, it should look something like this.
We can ignore the 53 ports.
Now, let's scroll all the way to the bottom of the page to
Advanced container settings.
Looking back at the PiHole quickstart on DockerHub, it doesn't look like we need to configure anything on this tab.
Let's click on the Volumes take to configure some persistent data.
The PiHole specification requires us to add the following volumes.
Again, the left-hand side of the colon
: is our host machine, the right-hand side is the Docker Container.
map additional volume then make sure that you click Bind.
Now, we can skip the Network tab and move over to the Env tab. This is where we configure the Environment Variables for the Container.
Once again, checking the PiHole requirements.
You'll see that
WEBPASSWORD is commented out here. We're going to specify one to save time changing our password from a randomly generated one later.
You know the drill.
Finally, let's set our Restart policy to Always. This is so that if we ever reboot our server, PiHole will spin back up.
Starting the container
After all that configuration, we can now start the PiHole service. Scroll up slightly and click the
Deploy the container button.
You'll then see
Deployment in progress
This might take some time as it needs to pull down the PiHole image from the DockerHub.
You'll then be redirected back to the Container List page. You see that PiHole is now starting up. We can check the status of this by clicking on the logs icon.
Eventually, PiHole should spin up. You'll see the following on your Container List page.
You can now navigate to your server IP address.
That's all there is to it. Hopefully, you can see the power of Portainer and how easy it is to configure Docker services on your instance. You now have an easy to use admin control panel for all of your services. Meaning that you can check the logs of your running containers, view the resources being used by each container. You could even set up an external endpoint for your Docker containers.
Please let us know if you get stuck along the way. We're happy to help you out.