Portainer Setup

Debian / Ubuntu

OpenSUSE MicroOS

Overview

Install Portainer to manage containers.

Assumptions

• Podman Setup completed.

• Logged in as administrative user.

Configure System

Firewall

Open port 9443 for the Portainer admin interface.

sudo firewall-cmd --permanent --zone=public --add-port=9443/tcp && sudo firewall-cmd --reload

Review the Portainer documentation on ports . Open the necessary ports for features the system is inteded to use.

• TCP port 9443 (or 30779 for Kubernetes with NodePort) for the UI and API.
• TCP port 8000 (or 30776 for Kubernetes with NodePort) for the TCP tunnel server for Edge Agents. This port is optional and only required if using Edge Compute features with Edge Agents.
• TCP port 9001 (or 30778 for Kubernetes with NodePort) must be accessible on the Agent from the Portainer Server instance.

Quadlet

Connect

Assuming Podman is running rootless, start a MachineCTL shell as the Podman user.

sudo machinectl shell --uid=podmanu

Podman Restart

Enable the Podman restart service so the Portainer container can be started at boot.

systemctl enable --user --now podman-restart.service

Quadlet File

Verify the containers/systemd configuration directory exists for the user.

mkdir -p $HOME/.config/containers/systemd

Get the UID of the Podman user. Note this for use in the Quadlet file.

id -u

Create a new Quadlet file for Portainer, portainer.container.

vim $HOME/.config/containers/systemd/portainer.container

[Unit]
Description=Portainer
Documentation=https://docs.portainer.io/
After=podman.socket
Wants=network-online.target
StartLimitIntervalSec=600
StartLimitBurst=3

[Container]
Image=docker.io/portainer/portainer-ce:latest
ContainerName=portainer
PublishPort=9443:9443
# Replace UID_HERE with UID
Volume=/run/user/UID_HERE/podman/podman.sock:/var/run/docker.sock
Volume=portainer_data:/data
SecurityLabelDisable=true

[Service]
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

Start Portainer

Reload systemd to apply changes.

systemctl --user daemon-reload

Start and verify its status with systemctl. It cannot be enabled with the systemctl enable command; the WantedBy definition will make podman-restart.service automatically start the container at boot.

systemctl --user start portainer

systemctl --user status portainer

Portainer Dashboard

With the Portainer container running on Podman, and the dashboard port open, connect to Portainer in a browser. Replace 0.0.0.0 with the IP address of the Portainer system. If a custom port was configured, also replace 9443.

When prompted, enter a generated (64 character max) password for the admin Portainer user. Select Create user and the dashboard will redirect to the Quick Setup page.

https://0.0.0.0:9443/

On the Quick Setup page will, the local socket should automatically appear after a few seconds. Should it not appear, verify the socket definition in the Portainer command is correct. Select the local socket environment.

The local Podman system will now be available to Live Connect via Portainer; ready to connect and deploy containers.

Portainer Settings

Some basic initial configuration can be completed once logged in.

General

Navigate to the General tab under Settings in the Portainer menu.

In the SSL cerrtificate section, enable Force HTTPS only, then Save SSL settings.

Authentication

Navigate to the Authentication tab under Settings in the Portainer menu.

Consider decreasing the Session lifetime to 1 hour or 4 hours.

In Password rules, increase the minimum password length to 18 characters.

Errors

Failed Unit

When using a Podman Quadlet, the Portainer service cannot be enabled because it is a generated service. Verify WantedBy=default.target is in the Quadlet, and the podman-restart.service is enabled.

Failed to enable unit: Unit /run/user/###/systemd/generator/portainer.service is transient or generated

Unable to Hash Data

An error may occur when attempting to create the Portainer admin user, this is most commonly because the entered password was too long. The max length for the Portainer password is 64 characters.

Failure
Unable to hash data

References

^{1 2 3}