# Portainer - a Web UI of Docker
---

[TOC]

## Overview

Portainer is a popular Docker UI that helps you visualise 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’ll be keeping it simple and using Portainer to manage a local Docker installation.

Two editions of the software are available, the free and open-source CE and commercial Business. The extra capabilities of Business are mostly focused on enhanced access, quota management, and administrator controls.

## Install Portainer

Make sure you’ve got Docker installed and running before proceeding any further. Docker 19.01 is required for all Portainer features to be fully supported.

First of all, you’ll need to create a new Docker volume. Portainer will use this to store its persistent data. Ours is going to be called <code>portainer_data</code>.

docker volume create portainer_data

Next, 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

This command will pull the portainer/portainer-ce image and start a new container from it. The container will be detached and executing in the background (-d).


The volume created earlier is mounted to /data within the container, where Portainer stores all its application data. The host’s Docker socket is also mounted into the container, so that Portainer has access to your machine’s Docker instance. Finally, port 9000 on the host is bound to port 9000 within the container. This is the port Portainer exposes its web UI on.

## First Run

You can now login to Portainer by visiting <code>http://localhost:9000</code> in your browser. You’ll need to set a password for the admin user upon first use. You’ll then land on the Home screen.


Before beginning to use Portainer, it’s worth looking at the app’s own configuration options. Click 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 usage statistics collection. Most of the settings should be fairly self-explanatory, with the majority focused on limiting the power afforded to non-administrator users.


The “Authentication” submenu in the navigation bar lets you configure how users login to 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 out the form fields to setup your preferred authentication system. When using the built-in users database, you can use the “Users” link in the sidemenu to create additional users and sort them into teams.

## Endpoints

Portainer lets you manage multiple Docker endpoints. To begin with, you’ll see a single “local” endpoint, representing the Docker Engine running on your own machine.


To add an additional endpoint, click the “Endpoints” link in the sidebar. Next, click the blue “Add endpoint” button. Choose the type of endpoint you’ll be using and supply your connection details.

All being well, you’ll be able to add your endpoint. It’ll show up as a new selectable tile on the Portainer homescreen. Detailed guidance on adding additional endpoints is outside the scope of this introductory guide as success will require correct configuration of the host you’re connecting to.

## Managing Containers

You’re now ready to begin using Portainer to interact with Docker. From the homescreen, click your “local” endpoint. It will become selected within Portainer, giving you access to the full management UI. You’ll arrive at a simple dashboard giving you an overview of your containers, images and volumes.


Click “Containers” on the dashboard or in the sidebar to open the container management screen. You’ll see a table displaying all your Docker containers.


To take an action against a container, click the checkbox next to its name. You can now use the button row at the top of the screen to start, stop, restart or remove the container. Containers which are currently running will show a green “running” state while stopped ones get a red “stopped”.

If you’re using a fresh Docker installation, your only container might be Portainer itself. Take care not to stop this container, as it’s serving the Portainer web UI you’re using!


Click the name of a container to view and change its details. This screen allows you to inspect the container’s properties, create a new Docker image from its current state and manage its network connections.

At the top of the screen, you’ll find five buttons under “Container status” that allow you to view the container’s logs (“Logs”), inspect its Docker manifest (“Inspect”), view resource usage statistics (“Stats”), access 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 may also edit an existing container – effectively destroying it and replacing it with a new one with modified 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. Next, specify the Docker image to use. For public images on Docker Hub, such as wordpress:latest, you can type an image name without providing any additional configuration.


To use images stored within a private registry, you’ll first need to add the registry’s details to Portainer. Click the “Registries” 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’ll then be able to select it in the “Registry” dropdown on the container creation screen. You may also use the Registries screen to set credentials for Docker Hub connections, allowing you to pull private images and avoid the rate limits applied to unauthenticated users.

You’re now ready to deploy your container by pressing the “Deploy the container” button at the bottom of the form. Before proceeding, review the additional settings which are displayed above the button. You can configure port binding, force Portainer to pull the image before deploying and choose to remove the container automatically when it exits.


At the bottom of the screen, you’ll find an advanced settings UI that offers even more options – too many to cover exhaustively here. These replicate the entire functionality of the <code>docker run</code> CLI command, enabling you to set up the container’s command, entrypoint, volumes, network interfaces and environment variables. Much of this UI should feel intuitive if you’re already familiar with Docker’s capabilities.

## Using Container Stacks

The container creation screen only permits you to spin up one container at a time. Portainer has built-in support for “stacks” which allow you to deploy linked containers. This functionality is based on docker-compose version 2.


Click the “Stacks” item in the navigation bar, then press the “Add stack” button. There’s no support for creating stacks graphically – you have to paste or upload a docker-compose.yml file. You may also choose to connect to a Git repository and use its docker-compose.yml directly.


Before deploying the stack, you’re able to set environment variables that will be made available to the containers. Choose which level of Portainer access control to apply and then click “Deploy the stack”. Portainer will pull all the images and create all the containers specified by the Compose file.


Select your stack from the Stacks screen to manage its containers collectively. You can stop all the containers in the stack, or delete the stack entirely, using the buttons at the top of the screen. There’s also controls to duplicate the stack or create a reusable template from its current state.


Templates can be accessed from the stack creation screen and allow you to quickly spin up new instances of frequently used services. Portainer also ships with a number of built-in templates, accessible from the “App Templates” link in the navigation bar.

## Portainer’s Convenience

Portainer helps you quickly create, manage and monitor Docker containers. It provides a graphical interface to Docker CLI commands that can sometimes become long and unwieldy. It also makes Docker accessible to users who may be unfamiliar with command-line interfaces.


Besides its container management capabilities, Portainer also provides visibility into the other fundamental Docker resources. The Images screen allows you to view, pull, import, export and delete the images available on your endpoint. The Networks and Volumes screens act similarly, enumerating and providing control over their respective resources. Finally, the Events table offers a comprehensive listing of all the actions taken by the Docker engine. This can be useful when reviewing past actions and identifying when certain containers were created or destroyed.