Installing and Using Portainer

Hostman Team

Technical writer

Docker

07.05.2024

Reading time: 12 min

Portainer is a container management tool that seamlessly works with both Docker and Kubernetes.

It is available in two versions:

free and open Community Edition;
paid Business Edition with additional features for corporate clients.

In this article, we will focus on installing Portainer on Ubuntu 22.04 with Docker and using the Community Edition. Although we will use Ubuntu as an example, most of the steps are similar for other operating systems, making this tutorial applicable to a variety of use cases.

Portainer is excellent for both beginners and professionals. Its intuitive graphical interface greatly simplifies management, making container technology accessible even to those new to the field. Experienced users will also find a rich selection of options for fine-tuning and personalization.

The article will focus on installing, overviewing the main functions and settings, connecting an external server as an environment, and providing a practical example of deploying WordPress on an external server using Portainer.

Prerequisites

A computer or a cloud server running a Linux-based OS such as Ubuntu, Debian etc.

In this article, we'll demonstrate installing Portainer on a local machine; however, if you plan to use it as a team, the application can also be installed on a cloud server, providing centralized management and accessibility to all team members.

Installing Portainer in Docker

Step 1: Install Docker and Docker Compose

Before installing Portainer, make sure Docker is installed on your system. If it is, you can skip this step. Otherwise, run the following commands to install:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

After installation, check the versions by running the commands:

docker -v
docker compose version

This will confirm successful installation and show the versions of installed programs.

Step 2: Create a working directory

Create a directory for the application in /opt and move to it:

cd /opt
sudo mkdir hostmanportainer
cd ./hostmanportainer

Step 3: Create a configuration file

Now create a docker-compose.yml file in the hostmanportainer directory. This file will describe the startup configuration. Use nano or any other text editor to create the file:

sudo nano docker-compose.yml

Paste the following content into the file:

version: "3.3"
services:
	hostmanportainer:
		image: portainer/portainer-ce:latest
		container_name: hostmanportainer
		environment:
			- TZ=Europe/London
		volumes:
			- /var/run/docker.sock:/var/run/docker.sock
			- /opt/hostmanportainer/portainer_data:/data
		ports:
			- "8000:8000"
			- "9443:9443"
		restart: always

Description of parameters:

version: "3.3": Indicates the version of Docker-compose you are using. Version 3.3 is suitable for most modern applications.
services: This section describes the services to start.
hostmanportainer: Service name. Used as an identifier.
image: portainer/portainer-ce:latest: Specifies the image to be used. The latest version of Community Edition is used here.
container_name: hostmanportainer: Assigns a name to the container to make it easier to identify.
environment: Allows you to set environment variables. For example, TZ=Europe/London sets the time zone of the container.
volumes:

/var/run/docker.sock: /var/run/docker.sock allows Portainer to communicate with Docker on your host;
/opt/hostmanportainer/portainer_data:/data creates a persistent data store.

ports:

"8000:8000" and "9443:9443" open the corresponding ports to access the Portainer. 9443 is used for HTTPS connection.

restart: always: Ensures that the container will automatically restart when necessary, for example after a server reboot.

Step 4: Launch

After creating the configuration file, run Portainer with Docker using the command:

docker compose up -d

Step 5: Access the Interface

Portainer is now running and accessible at https://<ip_or_localhost>:9443. Open this address in your browser to access the web interface.

Step 6: Create an Administrator Account

When you first log in, you will be asked to create an administrator account. Please note that the password requires a minimum of 12 characters. After completing the registration process, you will have access to the settings and container management functionality in the interface.

General Settings

To access the settings, go to the Settings section. Here we will cover the key settings that are most important for the basic configuration. We recommend reading the official documentation for a deeper understanding of all available settings.

Application settings. In this section, you can configure settings such as the frequency of creating state snapshots and sending anonymous application usage statistics.

App Templates. Here you can specify the URL of a JSON file with templates for quickly deploying containers. You can also use pre-installed templates, making launching new applications easier.
SSL certificate. This section allows you to upload your own SSL certificates for a secure connection. While this is not required for a local installation, attaching your own SSL certificate increases security when deploying Portainer on a remote server.

Backup up Portainer. This section allows you to create a backup copy of the application settings and configuration. It is useful for ensuring data security and simplifying migration to other systems.

Authentication. Here you can configure the user session duration and select the authentication method. The following methods are available in Community Edition: Internal (default), LDAP, and OAuth. However, it is worth noting that configuring OAuth in Community Edition has limitations, and popular services such as Microsoft OAuth, Google OAuth, Github OAuth are not supported, which requires manual configuration. When using Internal authentication, you can change the password requirements, such as reducing the minimum number of characters.

To change your password, go to the upper right corner of the screen, click on your account name and select My account. This will allow you to update your password and other personal settings.

After studying the basic settings, let's move on to other important sections available in the left menu of the interface.

Users. This section is for managing users. It is especially useful for working with a team as it allows you to restrict access to resources. Here you can create and manage individual users. In addition, in the Teams section you can create teams with different users for more granular access control. It should be noted that more advanced role settings are only available in the Business Edition.

Registries. In the Registries section, users can configure access to image repositories. The management interface facilitates integration with popular repositories such as DockerHub, AWS ECR, Quay.io, ProGet, Azure and GitLab, allowing you to efficiently manage container images directly through a graphical user interface.

Environments. The key section of Portainer for connecting to and managing external servers or environments. You can manage a variety of environments here, including Docker, Docker Swarm, Kubernetes, and ACI. Nomad is also available in the Business Edition. This section allows Portainer Server to manage multiple environments, simplifying scaling and infrastructure management.

Adding a new environment

To demonstrate the process of adding a new environment, we will connect a server on Ubuntu 22.04 with Docker pre-installed. This can be either a new server or a server on which containers are already running.

Start by clicking the Add environment button in the Environments section.
Select Docker Standalone and use the setup wizard by clicking Start Wizard.

During the setup process, select Agent and run the following command on the server that you plan to connect as an environment:

docker run -d\
-p 9001:9001\
--name portainer_agent\
--restart=always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/docker/volumes:/var/lib/docker/volumes \
portainer/agent:2.19.4

This command will launch the Portainer Agent, allowing Portainer Server to connect to the server and manage containers.

After successfully installing and launching the agent on the server, return to the web interface and complete the connection process by specifying the name of the environment and its address in the format server_ip:9001.
Click Connect to complete the connection. After successfully adding an environment, a pop-up notification Environment created will be displayed in the interface.

Environments Settings

When you go to the Home page, you will see two environments: local (the device where the application is running) and the previously added server. After selecting the previously added server, the menu on the left will update, adding management functions for the environment.

Environment Management

Images. The Images section displays all available images in the system. Here you can delete images individually or en masse, as well as download new images using the Pull image option.

Networks. The Networks page displays all available networks. Using an intuitive setup wizard accessible through Add Network, users can create new networks, expanding the connectivity between containers.

Volumes. The Volumes section contains information about all volumes. This section allows you to view existing volumes, delete them, or create new ones using the Add volume setup wizard.
Containers. The Containers section provides extensive container management capabilities. In this section, all existing containers are visible. You can delete, suspend, activate, or restart them. The Quick Actions menu provides additional functions, including viewing container information, statistics, and console access.

To create a new container, click on Add container. For example. let's create a container with Nginx. Specify the name, the nginx image and set up the network ports: click on publish a new network port and enter port 9090 for host, and port 80 for container.

Next, click on the Deploy the container button below and wait until the container is deployed.

Upon completion, you will be redirected to the Container list page. After deploying the container, going to http://server_ip:9090 will show running Nginx.

Advanced Features: App Templates and Stacks

The App Templates section is a collection of pre-configured templates for deploying common applications and services. These templates are designed to simplify the process of creating new containers by minimizing the need for manual configuration. Users can choose from a variety of available templates that range from basic web servers to complex multi-tier applications.

When using a template, it is enough to specify some basic parameters, such as the container name, network settings and, in some cases, specific settings such as passwords or environment variables. This makes the App Templates section particularly useful for quickly testing new ideas and utilities, as well as learning and experimenting with new technologies.

Stacks are an efficient way to manage groups of containers. They are defined through docker-compose files. This simplifies the management of complex applications and provides automation and consistency in deployment.

Use Case: Using Stacks for WordPress Deployment

A special feature of Stacks is choosing the configuration definition method: you can use the built-in editor to directly write or edit Docker Compose files, download a ready-made docker-compose.yml file, or even connect a git repository to update and deploy containers automatically.

Now let's put this technology into practice. Using WordPress deployment as an example, we'll show you how to use Stacks to create and manage multi-container applications. This example will help you understand how to simplify and automate your application deployment processes using Stacks.

In the Stacks section, click Add stack to open the configurator.
Using the Web editor, describe the application configuration in YAML format. For WordPress and MariaDB database, the configuration might look like this:

services:
	db:
		image: mariadb:10.6.4-focal
		command: '--default-authentication-plugin=mysql_native_password'
		volumes:
        	- db_data:/var/lib/mysql
 		restart: always
    	expose:
			- 3306
 			- 33060
		environment:
			- MYSQL_ROOT_PASSWORD=hostmantest
			- MYSQL_DATABASE=hostman_wp
			- MYSQL_USER=hostman
			- MYSQL_PASSWORD=password
 	wordpress:
 		image: wordpress:latest
 		ports:
 			- 80:80
 		restart: always
		environment:
   			- WORDPRESS_DB_HOST=db
   			- WORDPRESS_DB_USER=hostman
   			- WORDPRESS_DB_PASSWORD=password
   			- WORDPRESS_DB_NAME=hostman_wp
volumes:
    db_data:

Environment variables can be placed in a separate section. In Environment variables select Advanced mode and specify the variables:

MYSQL_ROOT_PASSWORD=hostmantest
MYSQL_DATABASE=hostman_wp
MYSQL_USER=hostman
MYSQL_PASSWORD=password
WORDPRESS_DB_HOST=db
WORDPRESS_DB_USER=hostman
WORDPRESS_DB_PASSWORD=password
WORDPRESS_DB_NAME=hostman_wp

Remove the environment section from the main YAML file to avoid duplication:

services:
  db:
    image: mariadb:10.6.4-focal
    command: '--default-authentication-plugin=mysql_native_password'
    volumes:
      - db_data:/var/lib/mysql
    restart: always
    expose:
      - 3306
      - 33060
  wordpress:
    image: wordpress:latest
    ports:
      - 80:80
    restart: always
volumes:
    db_data:

Click Deploy the stack. A bit later, if the deployment is successful, you will be redirected to the Stacks list page, where our Wordpress instance will be displayed.

Test your WordPress functionality by going to http://server_ip:80. You should see the WordPress start page, confirming successful deployment.

Conclusion

In our review, we covered all the important aspects of working with Portainer, from its installation with Docker to the details of deploying applications through Stacks. We took a detailed look at the tool's various features and settings, including user management, image repository handling, and environment coordination. The WordPress deployment example clearly showed how Portainer simplifies working with complex systems, making the management process more efficient. The article provided a comprehensive understanding of Portainer as a solution to simplify and streamline application deployment processes.