How To Install Portainer on Ubuntu

Managing Docker containers through command-line interfaces can be overwhelming, especially for beginners or those who prefer visual interfaces. That’s where Portainer comes in—a powerful, lightweight management tool that transforms Docker container management into an intuitive web-based experience. In this comprehensive guide, you’ll learn exactly how to install Portainer on Ubuntu, from initial setup to advanced configuration.

Table of Contents

What is Portainer and Why Use It?

Portainer is an open-source container management platform that provides a user-friendly web interface for managing Docker environments. Think of it as your Docker control center—instead of memorizing complex command-line instructions, you can manage containers, images, networks, and volumes through an elegant graphical interface.

Understanding Portainer’s Core Features

Portainer offers a comprehensive suite of features that make Docker management accessible to users of all skill levels:

Visual Container Management: Create, start, stop, and delete containers with simple clicks
Image Repository Management: Pull, push, and manage Docker images through the GUI
Network and Volume Control: Configure Docker networks and persistent storage visually
Real-time Monitoring: Monitor container performance, logs, and resource usage
Multi-environment Support: Manage multiple Docker hosts from a single interface

Portainer Community Edition vs Business Edition

Portainer offers two main editions to suit different needs:

Community Edition (CE):

Free and open-source
Perfect for home labs and individual use
Basic container management features
Community support only

Business Edition (BE):

Designed for enterprise environments
Advanced features including RBAC and registry management
Commercial support available
License required for more than 3 nodes

For most Ubuntu users getting started with container management, the Community Edition provides all necessary features.

Benefits of Using Portainer for Docker Management

Why choose Portainer over command-line Docker management? Here are compelling reasons:

Reduced Learning Curve: New users can start managing containers immediately without memorizing Docker commands
Improved Productivity: Visual interfaces speed up common tasks like container deployment and monitoring
Better Oversight: Dashboard views provide instant insights into your container ecosystem
Error Reduction: GUI-based management reduces syntax errors common in command-line operations

Prerequisites for Installing Portainer on Ubuntu

Before diving into the installation process, ensure your system meets the necessary requirements.

System Requirements

Your Ubuntu system should have:

Minimum RAM: 512MB (1GB recommended for better performance)
Storage Space: At least 1GB free space for Docker and Portainer
Network Access: Internet connection for downloading packages and images
Architecture: Compatible with x86_64 (amd64) systems

Ubuntu Version Compatibility

Portainer works seamlessly with modern Ubuntu versions:

Ubuntu 24.04 LTS (Latest)
Ubuntu 22.04 LTS (Most common)
Ubuntu 20.04 LTS (Still supported)
Ubuntu 18.04 LTS (Minimum supported version)

User Permissions and Access Requirements

You’ll need:

Sudo access for installing packages and configuring services
Terminal access to execute installation commands
Network permissions to access ports 8000, 9000, and 9443

Installing Docker on Ubuntu (Required for Portainer)

Since Portainer runs as a Docker container, installing Docker is our first crucial step.

Updating Your Ubuntu System

Start by ensuring your Ubuntu system has the latest package information:

sudo apt update && sudo apt upgrade -y

This command updates the package list and upgrades installed packages to their latest versions.

Installing Docker from Default Repositories

The simplest method to install Docker on Ubuntu is using the default repositories:

sudo apt install docker.io -y

This command installs Docker along with all necessary dependencies. The -y flag automatically answers “yes” to installation prompts.

Starting and Enabling Docker Service

After installation, start the Docker service and enable it to run automatically at boot:

sudo systemctl start docker
sudo systemctl enable docker

Verifying Docker Installation

Confirm Docker is running properly:

sudo systemctl status docker

You should see output indicating Docker is “active (running)”.

Adding User to Docker Group

To run Docker commands without sudo, add your user to the docker group:

sudo usermod -aG docker $USER

Important: Log out and back in (or start a new terminal session) for this change to take effect.

Installing Portainer on Ubuntu

With Docker successfully installed, we can now install Portainer using Docker containers.

Creating Persistent Docker Volume

First, create a Docker volume to store Portainer’s data persistently:

docker volume create portainer_data

This volume ensures your Portainer configuration and data survive container updates and restarts.

Downloading and Running Portainer Container

Install and run Portainer using this single command:

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:lts

Let’s break down this command:

-d: Runs container in detached mode (background)
-p 8000:8000: Maps port 8000 for TCP tunnel server
-p 9443:9443: Maps port 9443 for HTTPS web interface
--name portainer: Names the container “portainer”
--restart=always: Automatically restarts container if it stops
-v /var/run/docker.sock:/var/run/docker.sock: Gives Portainer access to Docker
-v portainer_data:/data: Mounts persistent volume
portainer/portainer-ce:lts: Uses the latest LTS version

Understanding Portainer Port Configuration

Portainer uses several ports for different functions:

Default Ports Explained (8000, 9443, 9000)

Port 9443: Primary HTTPS web interface (recommended)
Port 8000: TCP tunnel server for Edge agent communication
Port 9000: Legacy HTTP interface (optional, less secure)

For enhanced security, always use port 9443 for web access. If you need the legacy HTTP port, add -p 9000:9000 to your docker run command.

Verify Portainer is running:

docker ps

You should see a container named “portainer” with status “Up”.

Initial Portainer Setup and Configuration

Now that Portainer is installed, let’s complete the initial setup through the web interface.

Accessing Portainer Web Interface

Open your web browser and navigate to:

https://localhost:9443

If you’re installing on a remote server, replace localhost with your server’s IP address.

Note: You’ll likely see a security warning about an untrusted certificate. This is normal—Portainer generates a self-signed SSL certificate by default. Click “Advanced” and “Proceed to localhost” to continue.

Creating Admin Account

Upon first access, Portainer requires you to create an admin account:

Enter a username (typically “admin”)
Create a strong password (minimum 12 characters recommended)
Click “Create user” to proceed

Important: Complete this setup within 5 minutes, or you’ll need to restart the Portainer container.

Selecting Docker Environment

After creating your admin account, Portainer will ask you to select a Docker environment. For local installations, choose “Get Started” to use the local Docker environment where Portainer is running.

SSL Certificate Configuration

By default, Portainer uses a self-signed SSL certificate. For production environments, consider:

Uploading your own SSL certificate through the Portainer settings
Using a reverse proxy with proper SSL certificates
Configuring Let’s Encrypt for automatic SSL certificate management

Navigating the Portainer Dashboard

Once logged in, you’ll see Portainer’s intuitive dashboard—your command center for Docker management.

Understanding the Main Interface

The Portainer dashboard provides several key sections:

Home: Overview of your Docker environment
App Templates: Pre-configured application templates
Containers: Manage running and stopped containers
Images: View and manage Docker images
Networks: Configure Docker networks
Volumes: Manage persistent storage
Events: View Docker system events

Managing Containers Through GUI

The Containers section is where you’ll spend most of your time. Here you can:

View all containers with their status, ports, and resource usage
Start, stop, restart, or remove containers with single clicks
Access container logs for troubleshooting
Open container consoles for direct interaction
Monitor resource consumption in real-time

Image Management Features

The Images section allows you to:

Pull new images from Docker Hub or other registries
View image details including size and creation date
Remove unused images to free up disk space
Build custom images using Dockerfiles

Common Portainer Commands and Operations

While Portainer provides a GUI, understanding equivalent Docker commands helps with troubleshooting and automation.

Container Lifecycle Management

Common container operations through Portainer:

Creating Containers: Use the “Add container” button, specify image name, ports, and environment variables. This equivalent to:

docker run -d --name mycontainer -p 8080:80 nginx

Managing Container States: Start, stop, and restart containers through the dashboard, equivalent to:

docker start mycontainer
docker stop mycontainer  
docker restart mycontainer

Volume and Network Management

Portainer simplifies complex Docker networking and storage:

Create Docker networks for container communication
Manage persistent volumes for data storage
Configure port mappings visually
Set up environment variables through forms

Monitoring Container Performance

Use Portainer’s monitoring features to:

Track CPU and memory usage in real-time
Monitor network traffic and connections
View container logs with filtering options
Set up alerts for resource thresholds

Security Best Practices for Portainer

Securing your Portainer installation is crucial for production environments.

Securing Portainer Access

Implement these security measures:

Use HTTPS only: Always access Portainer via port 9443
Strong passwords: Enforce complex passwords for all users
Regular updates: Keep Portainer updated to the latest version
Firewall configuration: Restrict access to Portainer ports

User Management and RBAC

Portainer Community Edition provides basic user management:

Create separate user accounts for different team members
Use local authentication or integrate with external systems
Implement least privilege access principles

For advanced RBAC features, consider upgrading to Portainer Business Edition.

Network Security Considerations

Protect your Portainer installation:

Bind to specific interfaces: Don’t expose Portainer to public networks unnecessarily
Use reverse proxies: Implement additional security layers with nginx or Apache
Regular backups: Backup Portainer data and configurations regularly

Troubleshooting Common Installation Issues

Even with careful installation, you might encounter issues. Here’s how to resolve common problems.

Port Conflicts and Resolution

If you encounter port conflicts:

Check existing services: sudo netstat -tlnp | grep :9443
Stop conflicting services or use different ports
Modify Portainer ports: Use -p 9444:9443 in your docker run command

Docker Socket Permission Issues

If Portainer can’t access Docker:

sudo chmod 666 /var/run/docker.sock

Note: This is a temporary fix. The proper solution is adding your user to the docker group as described earlier.

Container Startup Problems

If Portainer won’t start:

Check Docker logs: docker logs portainer
Verify volume permissions: Ensure the docker user can write to mounted volumes
Restart Docker service: sudo systemctl restart docker

Updating and Maintaining Portainer

Keep your Portainer installation current and healthy.

Checking for Updates

Portainer displays update notifications in the dashboard when new versions are available. To update:

Stop the current container: docker stop portainer
Remove the old container: docker rm portainer
Pull the latest image: docker pull portainer/portainer-ce:lts
Start new container with the same command used for initial installation

Backup and Restore Procedures

Protect your Portainer configuration:

Backup: The portainer_data volume contains all configuration. Back it up regularly:

docker run --rm -v portainer_data:/data -v $(pwd):/backup alpine tar czf /backup/portainer_backup.tar.gz -C /data .

Restore: If needed, restore from backup:

docker run --rm -v portainer_data:/data -v $(pwd):/backup alpine tar xzf /backup/portainer_backup.tar.gz -C /data

Frequently Asked Questions

1. Can I install Portainer without Docker on Ubuntu?
No, Portainer requires Docker to function since it runs as a Docker container itself. Docker acts as the underlying container runtime that Portainer manages through its web interface.

2. What’s the difference between ports 9000 and 9443 in Portainer?
Port 9443 provides HTTPS access with SSL encryption and is the recommended secure method for accessing Portainer. Port 9000 offers HTTP access without encryption and should only be used in development environments or when behind a secure reverse proxy.

3. How much system resources does Portainer consume on Ubuntu?
Portainer is lightweight, typically using less than 100MB of RAM and minimal CPU resources. The exact usage depends on the number of containers you’re managing and the frequency of operations performed through the interface.

4. Can I manage remote Docker hosts with Portainer installed on Ubuntu?
Yes, Portainer supports managing multiple Docker environments including remote hosts, Docker Swarm clusters, and Kubernetes clusters. You can add remote endpoints through the Portainer interface after initial setup.

5. What should I do if I forgot my Portainer admin password?
If you forget your admin password, you’ll need to reset Portainer by stopping the container, removing the portainer_data volume (which deletes all configuration), and performing a fresh installation. Always backup your configuration to avoid data loss.