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.
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
:rodoes 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
rooton 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:
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yamlPaste this configuration:
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_dataPort 8000 is not published, because it is only used by Edge Agents. Validate the file and download the image:
docker compose config --quiet
docker compose pullStep 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:
ssh -N -L 9443:127.0.0.1:9443 YOUR_USER@YOUR_SERVER_IPThe 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:
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1The 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
- Open
https://localhost:9443in your browser. - Accept the security warning: Portainer uses a self-signed certificate by default. The traffic goes through the SSH tunnel.
- Choose a username and a unique password of at least 12 characters.
- Paste the token value into the Setup token field, then confirm.
- On the Edge Compute screen, choose Skip if you do not manage any Edge Agents.
- 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:
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443The 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:
nmap -Pn -p 8000,9000,9443 YOUR_SERVER_IPNone 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:
ports:
- "127.0.0.1:9443:9443"
- "127.0.0.1:9000:9000"Apply the change:
cd /opt/portainer
docker compose up -dThen add this site to /etc/caddy/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:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyOpen 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:
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose imagesYour 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
- Open Settings, then scroll down to Back up Portainer.
- Enable Password protect and enter a password.
- 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:
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.gzThe 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:
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 -dUse 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:
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1If 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:
command: --trusted-origins https://portainer.your-domain.comA 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:
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