Installing Portainer on VPS: Easy

Software Installation — Step-by-Step

Now that your server is prepared and secured, you can proceed with installing Docker Engine and Portainer CE. We will use current software versions for 2026, focusing on the latest stable releases.

1. Installing Docker Engine (version 26.0.x)

Docker Engine is the foundation on which Portainer and all your containers will run. We will install it from the official Docker repository to always have access to current versions.

1.1. Removing Old Docker Versions (if any)

If Docker was previously installed on the server, it is recommended to remove all old versions to avoid conflicts.

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt remove $pkg; done

1.2. Installing Necessary Utilities

Install the packages required to work with HTTPS repositories and GPG keys.

sudo apt update
sudo apt install ca-certificates curl gnupg -y

1.3. Adding the Official Docker GPG Key

Add the Docker GPG key so your system can verify the authenticity of packages from the Docker repository.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

1.4. Adding the Docker Repository to APT Sources

Add the official Docker repository for Ubuntu 24.04 (codename Noble Numbat) to your system's package sources list.

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

1.5. Installing Docker Engine, Containerd, and Docker Compose

Update the package list and install Docker Engine, as well as Containerd (container runtime) and Docker Compose (a tool for defining and running multi-container Docker applications).

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

1.6. Adding User to the Docker Group

To be able to run Docker commands without sudo, add your user to the docker group.

sudo usermod -aG docker $USER
newgrp docker # Applies changes to the current session without re-login

After running newgrp docker, try executing a Docker command without sudo. If you did not use newgrp docker, you will need to log out of your SSH session and log back in for the changes to take effect.

1.7. Verifying Docker Installation

Ensure that Docker Engine is installed and running correctly by running the hello-world test container.

docker run hello-world

The output should contain a message indicating that your Docker installation is working.

2. Installing Portainer CE (version 2.21.x)

Now that Docker is installed, you can deploy Portainer CE as a Docker container. We will use the latest stable version of Portainer CE, which will be current for 2026 (e.g., 2.21.x).

2.1. Creating a Volume for Portainer Data

Portainer stores its configuration data, databases, and settings in a persistent volume. Create it so that data is preserved even when the Portainer container is updated or recreated.

docker volume create portainer_data

2.2. Running the Portainer Container

Run Portainer CE in a container. We will configure it to start automatically when the server boots and bind the necessary ports and volumes.

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

Let's break down the command parameters:

• -d: Runs the container in detached mode.
• -p 8000:8000: Maps host port 8000 to container port 8000. Used for communication with the Edge Agent if you will be managing remote Docker environments.
• -p 9443:9443: Maps host port 9443 to container port 9443. This is the main port for accessing the Portainer web interface via HTTPS.
• --name portainer: Assigns the name portainer to the container for easy management.
• --restart always: Ensures that the Portainer container will automatically restart if the server stops or reboots.
• -v /var/run/docker.sock:/var/run/docker.sock: Mounts the Docker socket from the host system into the Portainer container. This allows Portainer to interact with the local Docker Engine.
• -v portainer_data:/data: Mounts the portainer_data volume we created into the /data directory inside the container, where Portainer stores its data.
• portainer/portainer-ce:latest: Specifies the Portainer Community Edition Docker image. The latest tag will always point to the latest stable version.

2.3. Checking Portainer Container Status

Ensure that the Portainer container is running correctly.

docker ps -a | grep portainer

The output should show a container named portainer with a status of Up.

Portainer is now installed and running. In the next step, we will proceed with its initial setup and ensure secure access via HTTPS.

Configuration

After successfully installing Portainer, it's time for its initial setup and securing access. We will configure web interface access, create an administrator, and most importantly, ensure an HTTPS connection using the Caddy reverse proxy and automatic Let's Encrypt certificates.

1. Initial Access to Portainer UI

Open your web browser and navigate to https://your_vps_ip:9443. You will be greeted by the Portainer initial setup page.

1. Create an administrator user: Enter a username (e.g., admin) and a strong password. Make sure to use a complex password.
2. Environment selection: After creating the user, Portainer will prompt you to choose which Docker environment you want to manage. Select "Get Started" to manage the local Docker environment on your VPS.

You will be taken to the Portainer dashboard. Note that by default, Portainer uses a self-signed SSL certificate, so your browser will issue a warning about an insecure connection. We will fix this by configuring Caddy.

2. Configuring TLS/HTTPS with Caddy (recommended)

Using Caddy as a reverse proxy is a modern and very convenient way to provide HTTPS for Portainer and your other applications. Caddy automatically obtains and renews Let's Encrypt certificates, which significantly simplifies TLS management.

2.1. Installing Caddy

We will install Caddy from its official repository.

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

After installation, Caddy will be running as a system service. Check its status:

sudo systemctl status caddy

It should be in an active (running) state.

2.2. Configuring the DNS record

For Caddy to obtain a Let's Encrypt certificate, you will need a domain name pointing to your VPS. Create an A-record with your domain registrar (e.g., portainer.yourdomain.com) and specify your VPS's IP address.

Wait for the DNS record to propagate across the network (this can take from a few minutes to several hours).

2.3. Configuring the Caddyfile

The Caddyfile is the main configuration file for Caddy. We will configure it to proxy requests from your domain to Portainer.

sudo nano /etc/caddy/Caddyfile

Remove the existing content and insert the following, replacing portainer.yourdomain.com with your domain name:

portainer.yourdomain.com {
    reverse_proxy localhost:9443 {
        transport http {
            tls_trust_panther_root
            insecure_skip_verify
        }
    }
}

Caddyfile explanations:

• portainer.yourdomain.com: Specifies the domain for which Caddy will handle requests and automatically obtain an SSL certificate.
• reverse_proxy localhost:9443: Redirects all incoming requests to local port 9443, where Portainer is running.
• transport http { ... }: This block is important because Portainer by default uses internal self-signed TLS on port 9443.
  • tls_trust_panther_root: Adds the Let's Encrypt root certificate to trusted certificates.
  • insecure_skip_verify: ATTENTION! This option disables backend certificate verification (Portainer). It is used here because Portainer uses a self-signed certificate. In production environments for other applications where the backend has a valid certificate, this option should not be used. For Portainer, this is acceptable as Caddy itself provides external TLS.

Save the file (Ctrl+O, Enter) and close the editor (Ctrl+X).

2.4. Applying Caddy Configuration

Check the Caddyfile syntax and reload the Caddy service.

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

If everything is configured correctly, Caddy will reload without errors. You can now access Portainer at https://portainer.yourdomain.com. Your browser will no longer issue security warnings, as Caddy will provide a valid SSL certificate from Let's Encrypt.

3. Verifying Functionality

Ensure that Portainer is accessible and functioning correctly via the domain name:

curl -I https://portainer.yourdomain.com

You should see an HTTP status of 200 OK or 302 Found (if Portainer redirects to the login page), as well as headers indicating a successful HTTPS connection.

4. Deploying a Test Container via Portainer

Let's deploy a simple Nginx web server to ensure that Portainer fully manages the Docker Engine.

1. Log in to Portainer via your domain (https://portainer.yourdomain.com).
2. In the left menu, select "Local" (under "Environments").
3. Go to "Containers", then click "Add container".
4. Fill in the fields:
   • Name: test-nginx
   • Image: nginx:latest
   • Port mappings: Click "publish a new network port".
     • Host port: 8080 (or any free port)
     • Container port: 80
     • Protocol: tcp
5. Click "Deploy the container".

After a few seconds, the test-nginx container should be running. Check it by opening http://your_vps_ip:8080 in your browser. You should see the standard Nginx welcome page.

Now you have a fully configured Portainer with secure access, ready to manage your Docker applications.

Backups and Maintenance

Ensuring regular backups and timely maintenance is critically important for any production system. In this section, we will cover what exactly needs to be backed up, how to automate this process, and how to keep your system up-to-date.

1. What to Back Up

For Portainer and your Docker applications, you need to regularly create backups of the following components:

• Portainer Data: This is the most important element. The portainer_data volume contains all Portainer configuration, user information, registries, stacks, networks, and volumes. Without it, restoring Portainer would mean losing all settings.
• Docker Volumes of Your Applications: All persistent data used by your containers (databases, user files, downloads) is stored in Docker volumes. Every volume marked as "persistent" or explicitly created should be backed up.
• Docker Compose Files: If you use docker-compose.yml to define your applications, these files are their "source code". Store them in a version control system (e.g., Git) and/or include them in regular backups.
• Configuration Files: Caddy configurations (/etc/caddy/Caddyfile), Fail2Ban settings (/etc/fail2ban/jail.local), and any other custom OS or application settings.

2. Simple Auto-Backup Script Using Restic

We will use Restic — a modern, fast, efficient, and encrypted backup tool. Restic supports many storage backends, including S3-compatible storage, SFTP, Backblaze B2, and others.

2.1. Installing Restic

Download the latest version of Restic and move the executable to /usr/local/bin.

# Check the current version at https://github.com/restic/restic/releases
RESTIC_VERSION="0.16.4" # Current as of 2026, may change
wget https://github.com/restic/restic/releases/download/v${RESTIC_VERSION}/restic_${RESTIC_VERSION}_linux_amd64.bz2
bzip2 -d restic_${RESTIC_VERSION}_linux_amd64.bz2
sudo mv restic_${RESTIC_VERSION}_linux_amd64 /usr/local/bin/restic
sudo chmod +x /usr/local/bin/restic

2.2. Configuring the Restic Repository

Create a Restic repository. As an example, we will use a local directory, but for production, it is highly recommended to use remote storage (S3, Backblaze B2, SFTP).

# Create a directory for the local repository (for example only)
sudo mkdir -p /mnt/backups/restic_repo
sudo chown $USER:$USER /mnt/backups/restic_repo

# Initialize the repository. Replace 'your_strong_password' with a VERY strong password.
# This password will be needed to access all your backups.
export RESTIC_PASSWORD="your_strong_password"
restic init --repo /mnt/backups/restic_repo

For S3-compatible storage (e.g., MinIO, AWS S3, DigitalOcean Spaces):

# Replace with your data
export AWS_ACCESS_KEY_ID="your_s3_access_key"
export AWS_SECRET_ACCESS_KEY="your_s3_secret_key"
export RESTIC_PASSWORD="your_strong_password"
restic init --repo s3:https://s3.your-region.amazonaws.com/your-bucket-name

2.3. Creating the Backup Script

Create the file /usr/local/bin/backup_script.sh:

sudo nano /usr/local/bin/backup_script.sh

Insert the following content:

#!/bin/bash

# --- Settings ---
# Path to the Restic repository
RESTIC_REPO="/mnt/backups/restic_repo" # Or s3:https://... for remote
# Password for the Restic repository
export RESTIC_PASSWORD="your_strong_password"
# Directory for temporary backup files (if needed)
BACKUP_TEMP_DIR="/tmp/docker_backups"

# What to back up
PATHS_TO_BACKUP=(
  "/var/lib/docker/volumes/portainer_data" # Portainer data
  "/var/lib/docker/volumes/your_app_data_volume" # Example: volume for your application
  "/etc/caddy/Caddyfile"                  # Caddy configuration
  "/etc/fail2ban/jail.local"              # Fail2Ban configuration
  "/opt/docker-compose-projects"          # Directory with docker-compose.yml files
)

# --- Functions ---
# Function to create Docker volume snapshots (Portainer itself is not stopped)
backup_docker_volume() {
    local volume_path=$1
    local volume_name=$(basename "$volume_path")
    echo "Creating temporary archive for Docker volume: $volume_name"
    # For Portainer_data, simply backing up the directory is sufficient
    # For other volumes, stopping the container might be required
    # or using 'docker run --rm -v $volume_name:/volume -v $BACKUP_TEMP_DIR:/backup alpine tar cvf /backup/$volume_name.tar /volume'
}

# --- Main script ---
echo "--- Starting backup $(date) ---"

# Create a temporary directory if needed for complex volume backups
# mkdir -p "$BACKUP_TEMP_DIR"

# Perform backup with Restic
/usr/local/bin/restic backup \
  "${PATHS_TO_BACKUP[@]}" \
  --repo "$RESTIC_REPO" \
  --verbose \
  --tag "daily-backup" \
  --exclude-file /root/.restic_exclude.txt # Example exclusion file, if needed

# Clean up old backups (retention policy)
echo "Cleaning up old snapshots..."
/usr/local/bin/restic forget \
  --repo "$RESTIC_REPO" \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --prune \
  --verbose

echo "--- Backup finished $(date) ---"

# Remove temporary directory
# rm -rf "$BACKUP_TEMP_DIR"

Make the script executable:

sudo chmod +x /usr/local/bin/backup_script.sh

Important: Replace your_strong_password with your actual Restic repository password. Never store passwords in plain text in production; it's better to use environment variables or Docker secrets. For a cron job, you can set RESTIC_PASSWORD directly in crontab.

For backing up Docker volumes other than portainer_data, it may be necessary to stop associated containers or use the command docker run --rm -v :/volume -v /tmp/backup:/backup alpine tar cvf /backup/.tar /volume to create a volume snapshot. However, for most applications that correctly handle IO, a direct backup of the volume directory is sufficient.

3. Automating Backups with Cron

Add the script to Cron for daily automatic execution.

crontab -e

Select an editor (if prompted) and add the following line to the end of the file so that the script runs every day at 3:00 AM:

0 3 * * * /usr/local/bin/backup_script.sh >> /var/log/backup.log 2>&1

This line will run the script daily at 3 AM and redirect all output to the file /var/log/backup.log for later analysis.

4. Where to Store Backups

Never store all backups on the same server as the original data. If the server fails, you will lose both data and backups.

• External S3-compatible storage: The recommended option. This can be AWS S3, Backblaze B2, DigitalOcean Spaces, MinIO, or any other object storage provider. It is reliable, scalable, and relatively inexpensive.
• Separate VPS: You can set up a second, less powerful VPS and use it exclusively for storing backups, for example, via SFTP or NFS.
• Local NAS/External Drive: If you manage a local server, you can use network-attached storage.

5. Maintenance and Updates

Regular updates are critically important for system security and stability.

• OS Update: Regularly run sudo apt update && sudo apt upgrade -y. For Ubuntu LTS, this can be done once a month or as important security patches are released.
• Docker Engine Update: Updates along with OS packages via apt upgrade. Always check release notes before major updates.
• Portainer Update:
  1. Stop the current Portainer container: docker stop portainer
  2. Remove the current container: docker rm portainer
  3. Download the new image: docker pull portainer/portainer-ce:latest
  4. Start a new container, using the same portainer_data volume:

     
     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
     

  Portainer will update using your existing data.

• Update Strategy:
  • Rolling updates: For non-critical systems, automatic updates can be configured, but this is risky.
  • Maintenance window: It is recommended to schedule updates during periods of minimal load, after thoroughly testing them on a staging server (if available).
• Log Monitoring: Regularly review system logs (journalctl -xe), Docker container logs (docker logs ), and Portainer logs to identify problems early.

Adhering to these practices will ensure the stability, security, and recoverability of your Docker infrastructure managed by Portainer.

Troubleshooting + FAQ

This section provides answers to frequently asked questions and solutions to common problems that may arise when installing and using Portainer on a VPS.

Cannot access Portainer via HTTPS through a domain.

What to check:

• DNS record: Make sure your A-record (e.g., portainer.yourdomain.com) correctly points to your VPS's IP address and has fully propagated across DNS servers. Check using dig portainer.yourdomain.com.
• UFW (firewall): Check if port 443 (HTTPS) is allowed in UFW. The command sudo ufw status verbose should show 443/tcp ALLOW Anywhere.
• Caddy service: Check if Caddy is running and if there are any errors in its logs. Commands: sudo systemctl status caddy and sudo journalctl -u caddy --no-pager.
• Caddyfile: Ensure that the configuration in /etc/caddy/Caddyfile is correct, the domain name is specified accurately, and you have reloaded Caddy after changes (sudo systemctl reload caddy).
• Portainer container: Make sure the Portainer container is running and listening on port 9443. Check using docker ps -a | grep portainer and docker logs portainer.

How to fix: Correct the DNS record, add a rule to UFW, check Caddyfile syntax, restart services.

Containers do not start or crash immediately after starting.

What to check:

• Container logs: The very first step is to check the logs of the problematic container. In Portainer, you can do this by navigating to the "Containers" section, selecting the desired container, and clicking "Logs". In the command line: docker logs <container_name_or_id>.
• Resource availability: Check if there is enough RAM and CPU on your VPS. Some containers require more resources than you might have anticipated.
• Volume settings: Ensure that all necessary volumes are mounted correctly and have the required permissions.
• Network settings: If the container needs to interact with other containers or the external network, make sure its network settings are correct.
• Errors in Dockerfile/docker-compose.yml: If you are using your own images or Docker Compose, check the files for syntax errors or incorrect paths.

How to fix: Analyze logs, adjust Dockerfile/docker-compose.yml, allocate more resources, check file and directory permissions used by volumes.

Docker commands require sudo, even though I added the user to the docker group.

What to check:

• Docker group: Make sure your user is indeed in the docker group. The command groups $USER should show docker among the groups.
• Re-login: After adding a user to the docker group, you need to exit the SSH session and log in again for the changes to take effect. Alternatively, run newgrp docker.

How to fix: Exit your SSH session and log in again, or run newgrp docker to update group membership for the current session.

What is the minimum VPS configuration suitable for Portainer and a couple of small applications?

For Portainer and 2-3 small applications (e.g., a web server, a database, a WordPress blog), a VPS with 2 vCPU, 2-4 GB of RAM, and 50-80 GB of SSD storage will be sufficient. This will ensure comfortable operation of Portainer and stable functioning of your services.

What to choose — VPS or dedicated for this task?

For managing Docker containers with Portainer and running most medium-sized projects (several dozen containers, average load), a VPS is the optimal choice. It is more economical, flexible, and easier to manage. A dedicated server is only needed if you plan to run very high-load applications, hundreds of containers, or if you require specific hardware (e.g., powerful GPUs) or complete physical resource isolation. For most users, a VPS will be more than sufficient.

How to update Portainer without data loss?

Updating Portainer usually occurs without data loss, as all important data is stored in the Docker volume portainer_data. The process is as follows:

1. Stop the current Portainer container: docker stop portainer.
2. Remove the old container: docker rm portainer.
3. Pull the latest version of the Portainer image: docker pull portainer/portainer-ce:latest.
4. Start a new container using the same parameters and the same portainer_data volume:

   
   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
               

After this, Portainer will start with the new version, using all your previous settings and data.

I forgot my Portainer administrator password. How do I reset it?

If you forgot your Portainer administrator password, you can reset it by following these steps:

# Stop the Portainer container
docker stop portainer

# Start a temporary container to reset the password
docker run --rm -it \
  -v portainer_data:/data \
  portainer/portainer-ce:latest \
  --admin-password "new_strong_password"

# Replace "new_strong_password" with your new password.
# After executing this command, the temporary container will be removed.

# Start the main Portainer container again
docker start portainer

Now you can log in to Portainer with your new password.

Conclusions and Next Steps

In this detailed guide, we successfully set up Portainer Community Edition on your VPS, transforming the complex process of managing Docker containers into an intuitive task using a web interface. You went through all stages: from server preparation and Docker installation to configuring secure access via Caddy with automatic SSL certificates, and implementing basic backup and maintenance practices. You now have full control over your Docker infrastructure, with a powerful tool for deploying, monitoring, and managing your applications.

Here are a few directions you can take to maximize the capabilities of your new environment:

• Explore additional Portainer features: Portainer offers many advanced features, such as Docker Compose stack management, application templates, team creation and role-based access control (RBAC), integration with image registries, and much more.
• Implement CI/CD: Integrate Portainer into your continuous integration and delivery (CI/CD) workflow. You can configure automatic deployment of new versions of your applications in Portainer after a successful build.
• Monitoring and logging: Consider installing a monitoring stack, such as Prometheus and Grafana, for in-depth analysis of your container and VPS performance. For centralized logging, you can use ELK Stack (Elasticsearch, Logstash, Kibana) or Grafana Loki.
• Scaling: If your needs grow, explore the capabilities of Docker Swarm or even Kubernetes. Portainer can manage Swarm and Kubernetes clusters, providing a unified interface for scaling your applications.

Your VPS is now a powerful and flexible platform for hosting all your projects, and Portainer makes managing this platform simple and efficient.