Portainer is a popular Docker UI that allows you to visualize your containers, images, volumes and networks. Portainer helps you take control of the Docker resources on your machine, avoiding lengthy terminal commands.
Portainer recently reached version 2.0 which added support for Kubernetes clusters. The tool also supports Docker Swarm and Azure ACI environments. In this tutorial we will keep it simple and use Portainer to manage a local Docker installation.
Two editions of the software are available, the free and open source CE and Commercial Business. Business̵
Make sure Docker is installed and running before proceeding. Docker 19.01 is required to fully support all Portainer functions.
First of all, you need to create a new Docker volume. Portainer will use this to store its permanent data. Ours will be called
docker volume create portainer_data
Then use Docker to start a new Portainer container:
docker run -d -p 9000:9000 --name=portainer --restart=unless-stopped -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce
With this command it becomes
portainer/portainer-ce image and start a new container from it. The container will be disconnected and run in the background (
The previously created volume is linked to
/data in the container, where Portainer stores all its application data. The host’s Docker connector is also mounted in the container, so Portainer can access the Docker instance of your machine. Finally, port 9000 on the host is bound to port 9000 in the container. This is the port where Portainer shows its web UI.
You can now log in to Portainer by going to
http://localhost:9000 in your browser. You need to set a password for it
admin user at first use. You will then be taken to the start screen.
Before you start using Portainer, it’s worth checking out the app’s own configuration options. Click on the “Settings” link in the left navigation menu. Here you can change Portainer security settings, set a custom application logo and opt out of anonymous collection of usage statistics. Most settings should be fairly self-explanatory, with the majority focused on limiting the power afforded to non-admin users.
The “Authentication” submenu in the navigation bar allows you to configure how users log into Portainer. Portainer uses its own internal user management system by default, but you can choose to use an existing LDAP server or OAuth provider. Select the method to use and then fill in the form fields to set up your preferred authentication system. If you are using the built-in user database, you can use the “Users” link in the side menu to create additional users and sort them into teams.
Portainer allows you to manage multiple Docker endpoints. To begin with, you will see a single “local” endpoint, which represents the Docker Engine running on your own computer.
To add an additional endpoint, click on the “Endpoints” link in the sidebar. Then click on the blue button “Add end point”. Choose the type of endpoint you will use and enter your connection information.
You should be able to add your end point. It is displayed as a new selectable tile on the Portainer home screen. Detailed guidelines for adding additional endpoints are beyond the scope of this introductory guide, as success requires proper configuration of the host you are connecting to.
You are now ready to start using Portainer to communicate with Docker. On the home screen, click on your “local” endpoint. It is selected within Portainer, giving you access to the full management interface. You will arrive at a simple dashboard with an overview of your containers, images and volumes.
Click on “Containers” on the dashboard or in the sidebar to open the container management screen. You will see a table of all your Docker containers.
To take action against a container, click the check box next to its name. You can now use the button row at the top of the screen to start, stop, restart or delete the container. Containers that are currently active will show a green “running” status, while stopped containers will show a red “stopped”.
If you’re using a fresh Docker installation, your only container may be Portainer itself. Make sure not to hold back this container as it serves the Portainer web UI you are using!
Click on the name of a container to view and edit its details. On this screen you can inspect the container properties, create a new Docker image from its current state and manage the network connections.
At the top of the screen, you will find five buttons under ‘Container Status’ that allow you to view the container logs (‘Logs’), the Docker manifest (‘Inspect’) and resource usage statistics (‘Stats’). ), open an interactive console (“Console”), or attach a console to the foreground process in the container (“Attach”).
Create a container
To create a new container, return to the Containers screen and click the blue “Add Container” button. You can also edit an existing container – effectively destroy it and replace it with a new one with changed properties – by using the “Duplicate / Edit” button on the container details screen. Both operations display the same interface.
First, type a name for your new container. Then specify the Docker image you want to use. For public images on Docker Hub, such as
wordpress:latest, you can type an image name without any additional configuration.
To use images stored in a private registry, you must first add the registry information to Portainer. Click on the “Registers” link under the Settings heading in the left sidebar. Press the blue “Add registry” button and define the URL, username and password of your registry. You can then select it from the “Register” drop-down list on the container creation screen. You can also use the Registries screen to set credentials for Docker Hub connections, so you can get private images and avoid the speed limits that apply to unauthenticated users.
You are now ready to deploy your container by clicking the “Deploy the Container” button at the bottom of the form. Before proceeding, check the additional settings shown above the button. You can configure port binding, force Portainer to fetch the image before deploying, and choose to automatically delete the container when it shuts down.
At the bottom of the screen, you’ll find an advanced settings user interface that offers even more options – too many to cover in full here. These replicate the full functionality of the
docker run CLI command, which allows you to set the container command, access point, volumes, network interfaces, and environment variables. Much of this user interface should feel intuitive if you are already familiar with Docker’s capabilities.
Using container stacks
In the container creation screen, you can run only one container at a time. Portainer has built-in support for “stacks” with which you can deploy linked containers. This functionality is based on
docker-compose version 2.
Click on the “Stacks” item in the navigation bar and then press the “Add Stack” button. There is no support for graphing stacks – you need one
docker-compose.yml File. You can also choose to connect to a Git repository and the
docker-compose.yml straight away.
Before deploying the stack, you can set up environment variables that are made available to the containers. Choose which level of Portainer access control to apply, then click “Deploy the stack”. Portainer will fetch all images and create all containers specified by the Compose file.
Select your stack on the Stacks screen to collectively manage the containers. You can put all containers in the stack, or delete the stack completely, using the buttons at the top of the screen. There are also controls to duplicate the stack or create a reusable template from its current state.
Templates are accessible from the stack creation screen and allow you to quickly start up new instances of frequently used services. Portainer also comes with a number of built-in templates, accessible from the “App Templates” link in the navigation bar.
Portainer helps you quickly create, manage and monitor Docker containers. It provides a graphical interface for Docker CLI commands that can get long and unwieldy at times. It also makes Docker accessible to users who may not be familiar with command line interfaces.
In addition to container management capabilities, Portainer also provides insight into the other fundamental Docker resources. In the Images screen, you can view, retrieve, import, export, and delete the images available on your endpoint. The Networks and Volumes screens work in the same way, they inventory and provide control over their respective resources. Finally, the events table provides a comprehensive list of all actions taken by the Docker engine. This can be useful for reviewing past actions and determining when certain containers were created or destroyed.