Installing Portainer on Docker: the essential GUI tool for container management

Hi! 🐳 Today we’re going to learn how to install Portainer, a powerful web-based GUI tool that makes managing your Docker environment easier and more efficient. If you’re not comfortable with complex CLI commands, or just want to get a bird’s eye view of the containers you’re running, Portainer will be an essential tool for you.

—.

💡 What is Portainer?

Portainer is an open source management tool that allows you to manage your Docker, Docker Swarm, and Kubernetes environments with a web-based interface. It greatly improves productivity by allowing you to visually perform almost any task related to Docker, including creating and managing containers, images, volumes, network settings, and more.

Benefits of using Portainer:

• Visual management: Create, start, stop, and delete containers with just a few clicks, no complicated commands.
• Easy accessibility: Access and manage your Docker environment from anywhere via a web browser.
• Increased productivity: Save time by quickly handling repetitive tasks with the GUI.
• Reduce errors: Reduce mistakes caused by CLI command typos and more.

—.

✅ Prerequisites

Before installing Portainer, please make sure you have the following things

1. Docker installation: You must have Docker Engine (including Docker Desktop) installed on your server or PC.
   • Linux: sudo apt-get install docker.io or sudo yum install docker-ce
   • Windows/macOS: Install from the Docker Desktop official website. Terminal/Command Prompt:** Basic terminal skills are required.
2. internet connection:** Required to download the Portainer image.

—.

🚀 Step-by-step guide to installing Portainer

Now let’s get down to installing Portainer, which is a very simple process!

Step 1: Create a Portainer data volume 📁💾

To ensure that Portainer’s settings and data are preserved even if the container is deleted, we’ll first create a Docker volume. This volume is where we will store the internal data used by Portainer.

docker volume create portainer_data

• Description: This command creates a Docker volume named portainer_data.

Step 2: Run the Portainer container 🚀✨

Now it’s time to download the Portainer image and run it as a container.

docker run -d -p 8000:8000 -p 9443:9443 \
  --name portainer --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

• Command Description: * -d: Detached mode
  • -d: Detached mode (runs the container in the background). The container will continue to run even if you close the terminal.
  • -p 8000:8000: Port mapping for HTTP connections. It connects port 8000 on the container to port 8000 on the host.
  • -p 9443:9443: Port mapping for HTTPS connections. Portainer uses HTTPS by default, and port 9443 is recommended.
  • --name portainer: Name the container portainer to make it easier to identify and manage.
  • --restart always: Set to always restart automatically when the Docker daemon is started or if the container is terminated unexpectedly.
  • -v /var/run/docker.sock:/var/run/docker.sock: This is the most important part! This setting mounts the Docker socket file so that Portainer can communicate with the host’s Docker daemon. This setting allows Portainer to manage the host’s Docker environment.
    • Windows/macOS Docker Desktop users Note: In a Docker Desktop environment, the path docker.sock is handled automatically, so you do not need to modify this path. In most cases, you can use the above command as is.
  • -v portainer_data:/data: Mount the portainer_data volume created in step 1 to the /data directory inside the container to permanently store Portainer’s data.
  • portainer/portainer-ce:latest: The name of the Docker image to use. The portainer-ce means Community Edition, and latest means to use the latest version.

If it runs successfully, the container ID will be printed to the terminal. You should now see the Portainer container running in the background.

If you want to check if the container is running well, try entering the following command:

docker ps

If the container named portainer appears to be Up, you’re good to go!

container id image command created status ports names
xxxxxxxxxxxx portainer/portainer-ce:latest "/portainer" 10 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, 0.0.0.0:9443->9443/tcp portainer

—.

🌐 Connecting to Portainer

Now it’s time to connect to Portainer via a web browser.

1. Check server IP: Check the IP address of the server where Portainer is installed.

   • Linux: Use the ip a or ifconfig command.
   • Windows/macOS (Docker Desktop): Mostly use localhost.

2. Browser connection: Open a web browser and connect to the following address.

   • HTTPS (recommended): https://[server IP or localhost]:9443
   • HTTP (optional): http://[server IP or localhost]:8000 (If you don’t get an HTTPS connection, try HTTP; most modern browsers default to HTTPS).

Example: https://localhost:9443 or https://192.168.1.100:9443

—]

🔐 初始設定 (First-time Setup)

The first time you connect, you’ll need to set a password for the Portainer admin account (admin).

1. Set password: Enter a strong password for the admin username, confirm it, and click the “Create user” button. ![Example of Portainer initial password setting screen] (I can’t include the actual screenshot, but you can imagine the screen with the “admin” username and password fields.)

2. Select an environment connection: Once you’ve finished setting the password, you’ll be presented with a screen to select the Docker environment you want Portainer to manage. We will be managing the local Docker environment where we currently have Portainer installed, so select the “Local” option under “Get Started” and click the “Connect” button. ![Example of Portainer environment connection selection screen] (You can imagine a screen with “Local” and “Remote” options and selecting “Local.”)

Once everything is set up, you will be taken to your Portainer dashboard – congratulations! 🎉

—]

👀 Explore Portainer

When you access the Portainer dashboard, you can get an overview of your current Docker environment at a glance. The left sidebar contains various menus.

• Dashboard: Shows the overall status of your Docker resources, including containers, images, volumes, and more.
• Containers: View and manage all your running and stopped containers. Create, start, stop, restart, delete, and more.
• Images: View a list of downloaded Docker images, and build or delete them.
• Volumes: Manage created data volumes.
• Networks: Create, manage, and view Docker networks.
• Stacks: Deploy and manage multiple containers at once using Docker Compose files.
• Registries: You can add and use other container registries in addition to Docker Hub.
• Users/Teams: You can manage accounts for multiple users to use Portainer.

—.

⚠️ Troubleshooting

Here are some common issues you may encounter during the installation process and how to resolve them.

• “Site cannot be reached” or “Connection refused” error: * Check if the Portainer container is running: Use the docker ps command to check if the Portainer container is running.

  • Make sure the Portainer container is running: Use the docker ps command to make sure the STATUS of the Portainer container is Up.
  • Port Conflict: Ports 9443 or 8000 may be in use by other applications.
    • Linux: Use the command sudo netstat -tulnp | grep 9443 (or 8000) to check if any processes are using that port, and if so, you should stop them or change the Portainer port.
    • Solution: Change the -p option in the Portainer run command to another available port. Example: -p 9000:9443

• “Error: Could not retrieve info from Docker daemon” or a permissions issue:

  • Check that the Docker daemon is running: Verify that the Docker service is running (e.g., sudo systemctl status docker or check that Docker Desktop is running)
  • Docker socket permissions: The /var/run/docker.sock file is not authorized to be accessed by the Portainer container.
    • Linux: Give the current user the docker group permissions: sudo usermod -aG docker $USER And reboot the system or log in again to apply the changes. After that, try restarting the Portainer container.

• If the container continues to exit with an “Exited” status:

  • Check the logs: Use the docker logs portainer command to check the container’s logs. There should be error messages in the logs, which can help you determine the cause of the problem.

—.

🎉 Wrapping up

You have now successfully installed Portainer to easily manage your Docker environment with a GUI! With Portainer, you can manage, deploy, and monitor your containers much more efficiently.

In the future, take advantage of Portainer’s many features to make your Docker environment even more powerful. If you have any questions or features you’d like to see more of, feel free to leave a comment! Happy container life! 👏