EN

Applications

Install Portainer CE and Secure Access to It

Install Portainer Community Edition with Docker Compose on Debian or Ubuntu: access through an SSH tunnel or restricted HTTPS, Docker socket risk, updates and backups.

10 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

Portainer Community Edition (CE) is a web interface for managing the containers, images, volumes, networks and stacks of a Docker server. This guide explains how to install it with Docker Compose without exposing its interface to the Internet.

By the end of the guide, Portainer listens only on the server's local address. You reach it through an SSH tunnel or, if you wish, over HTTPS from your IP address alone. You also know how to assess the risk tied to the Docker socket, update Portainer and back up its data.

Order a Server

This guide applies to servers that you administer yourself:

Prerequisites

  • A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
  • SSH access with a user that has sudo
  • Docker Engine and Docker Compose installed from the official repository, as explained in the guide Install Docker Engine and Docker Compose. Do not use the Docker snap package
  • An SSH client on your computer

The docker commands assume that your user belongs to the docker group. Otherwise, add sudo in front of them.

This guide uses version 2.45.3, the most recent LTS version at the time of writing. Check the latest version on the Portainer releases page and the list of supported Docker versions.

Ports Used

Port Purpose Publication in this guide To open in the firewall
22/tcp SSH and tunnel to Portainer The server's SSH service Yes, if it is not already open
9443/tcp Portainer HTTPS interface 127.0.0.1 only No
9000/tcp HTTP interface, for a local reverse proxy 127.0.0.1, only with the Caddy option No
8000/tcp Edge Agents tunnel Not published No
80 and 443/tcp Caddy Only with the Caddy option Only with the Caddy option

Understand the Docker Socket Risk

Portainer controls Docker through the /var/run/docker.sock socket, mounted in its container. This socket gives access to the entire Docker API, whose daemon runs as root.

An account that controls Docker can, for example, start a privileged container or mount the server's root / in a container, then read and modify any file. The Docker documentation points out that only trusted users should be allowed to control the daemon.

A few practical consequences:

  • Mounting the socket with :ro does not protect you: it applies to the file, not to the actions sent to the Docker API
  • Reserve the administrator role for people who could already be root on the server
  • Apply Portainer updates promptly
  • Prefer the SSH tunnel, which avoids exposing the interface

Step 1: Create the Compose Project

Create a folder for Portainer:

Terminal
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yaml

Paste this configuration:

YAML
services:
  portainer:
    image: portainer/portainer-ce:2.45.3
    container_name: portainer
    restart: unless-stopped
    ports:
      - "127.0.0.1:9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:
    name: portainer_data

Port 8000 is not published, because it is only used by Edge Agents. Validate the file and download the image:

Terminal
docker compose config --quiet
docker compose pull

Step 2: Open the SSH Tunnel

Portainer allows 5 minutes to create the first administrator after it starts. So prepare the tunnel before launching the container.

In a terminal on your computer, run:

Terminal
ssh -N -L 9443:127.0.0.1:9443 YOUR_USER@YOUR_SERVER_IP

The command prints nothing and stays active: this is normal. Leave this terminal open while you use Portainer, then close the tunnel with Ctrl+C. If port 9443 is already taken on your computer, use for example -L 19443:127.0.0.1:9443 and the address https://localhost:19443.

Step 3: Start Portainer

On the server, start the container, then retrieve the setup token:

Terminal
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1

The last command prints a setup_token=... line. This single-use token, required since versions 2.39.4 and 2.43, prevents a third party from taking over a new instance. It is regenerated at each startup as long as no administrator exists.

Step 4: Create the Administrator Account

  1. Open https://localhost:9443 in your browser.
  2. Accept the security warning: Portainer uses a self-signed certificate by default. The traffic goes through the SSH tunnel.
  3. Choose a username and a unique password of at least 12 characters.
  4. Paste the token value into the Setup token field, then confirm.
  5. On the Edge Compute screen, choose Skip if you do not manage any Edge Agents.
  6. In the wizard, click Get Started: the local environment is detected automatically.

Keep this password in a password manager.

Check the Result

In Portainer, open the local environment: the portainer container must appear in the Containers list.

Then check the listening address on the server:

Terminal
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443

The output must contain 127.0.0.1:9443->9443/tcp, and curl must return an HTTP response. Finally, from another machine, without a tunnel, check that nothing is reachable:

Terminal
nmap -Pn -p 8000,9000,9443 YOUR_SERVER_IP

None of these ports must appear as open.

Limit Permissions in Portainer

A few settings reduce the risks if several people use the interface:

Setting Location Recommendation
Individual accounts User-related > Users One account per person, without the administrator role unless necessary
Session lifetime Settings > Authentication Reduce the default value of 8 hours if needed
Docker restrictions local environment > Host > Setup > Docker Security Settings Enable in particular Hide bind mounts for non-administrators and Hide privileged mode for non-administrators

These restrictions only apply to non-administrator accounts. They do not limit what an administrator can do.

Option: Publish Portainer over HTTPS with Caddy

The SSH tunnel is enough in most cases. If you need a web address, place Portainer behind a reverse proxy and limit access to your IP address.

You must have followed the guide Caddy as a Reverse Proxy with Automatic HTTPS and created an A record for portainer.your-domain.com pointing to YOUR_SERVER_IP.

Add the local HTTP port to /opt/portainer/compose.yaml:

YAML
    ports:
      - "127.0.0.1:9443:9443"
      - "127.0.0.1:9000:9000"

Apply the change:

Terminal
cd /opt/portainer
docker compose up -d

Then add this site to /etc/caddy/Caddyfile:

caddyfile
portainer.your-domain.com {
	@allowed client_ip YOUR_IP

	handle @allowed {
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

Since Caddy is installed on the server and not in Docker, UFW applies to its ports. Open them, then reload the configuration:

Terminal
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Open https://portainer.your-domain.com from your allowed address: the login page must appear. From another connection, for example a phone on mobile data, the connection must be dropped.

If your IP address changes often, reserve access for a private network instead, using WireGuard or Tailscale.

Update Portainer

First back up Portainer, then read the release notes. Replace the image tag in compose.yaml with the new version, then run:

Terminal
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose images

Your other containers are not stopped. Then log back in to check that the local environment responds. The data stays in the portainer_data volume.

The floating lts tag also exists, but a specific version lets you choose when to update and know exactly what is running.

Back Up and Restore

A Portainer backup contains its database and the files of the stacks deployed from Portainer. It contains neither your containers, nor your images, nor the data in their volumes: back those up separately, as explained in the Docker guide.

From the Interface

  1. Open Settings, then scroll down to Back up Portainer.
  2. Enable Password protect and enter a password.
  3. Click Download backup.

In the CE edition, this backup is started manually. Scheduled backups and sending to S3 are reserved for the Business edition.

From the Server

This method can be scheduled. It stops Portainer for a few moments, without touching your other containers:

Terminal
cd /opt/portainer
mkdir -p backups
docker compose stop portainer
docker run --rm -v portainer_data:/data:ro -v "$PWD/backups":/backup alpine:3 tar czf "/backup/portainer-$(date +%F).tar.gz" -C /data .
docker compose start portainer
sudo chmod 600 backups/*.tar.gz

The archive contains credentials and API keys. Copy it, along with compose.yaml, off the server to an encrypted location.

Restore the Server Archive

Replace YYYY-MM-DD with the date of the archive. The current contents of the volume are deleted:

Terminal
cd /opt/portainer
docker compose down
docker run --rm -v portainer_data:/data -v "$PWD/backups":/backup:ro alpine:3 sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/portainer-YYYY-MM-DD.tar.gz -C /data'
docker compose up -d

Use the same Portainer version as when the backup was made, or a more recent one.

Restore a Downloaded File

This restoration is only possible on a new instance, with an empty volume. On the initialization screen, open Restore Portainer from backup, choose the file, enter its password and the setup_token, then click Restore Portainer.

Troubleshooting

the Portainer instance timed out for security purposes

The first administrator was not created within 5 minutes. Restart the container, then retrieve the new token:

Terminal
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1

If this message appears on an instance that is already configured, check that the portainer_data volume is mounted: without its data, Portainer behaves like a new installation.

The Setup Token Is Rejected

The token changes at each startup. Use the latest value printed by the previous command and copy it without any spaces.

open failed: connect failed: Connection refused

This message appears in the tunnel terminal. The tunnel works, but nothing is listening on the target port of the server. Check the container's status with docker compose ps and its logs with docker compose logs --tail=50 portainer.

bind [127.0.0.1]:9443: Address already in use

The port is already in use on your computer, often by an old tunnel. Close it or choose another local port, as in step 2.

Client sent an HTTP request to an HTTPS server

You are using http:// on port 9443. Open https://localhost:9443.

Port 9443 Responds from the Internet

The port was probably published without a local address. Check the output of docker ps: if it contains 0.0.0.0:9443, fix compose.yaml and run docker compose up -d again.

403 Forbidden and CSRF check failed Behind a Reverse Proxy

The proxy is probably changing the host name received by Portainer. With the Caddy block in this guide, the original name is preserved. If you have another proxy in front, declare the public address with a full URL:

YAML
    command: --trusted-origins https://portainer.your-domain.com

A name without https:// causes the invalid url for trusted origin error at startup.

502 Error with Caddy

Caddy cannot reach port 9000. Check that it is published with docker ps, then test curl -I http://127.0.0.1:9000. If Force HTTPS only is enabled, disable it through the SSH tunnel.

Lost Administrator Password

Another administrator can reset it. Otherwise, use the official tool, which prints a new password:

Terminal
cd /opt/portainer
docker compose stop portainer
docker pull portainer/helper-reset-password
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker compose start portainer

References