Skip to main content

Portainer - Container Manager

Portainer is a web interface for managing Docker (and Kubernetes) containers.

Access

Portainer is reverse-proxied by the Secure Web Application Gateway. It is published on swag.kasad.com/portainer.

The Portainer instance is protected by Cloudflare Access and requires two-factor authentication to access.

Deployment

Portainer runs as a single Docker container using the portainer/portainer-ce:latest image. Here is the Docker Compose service entry for it:

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /srv/portainer/data:/data
    networks:
      - default
      - swag

networks:
  swag:
    name: swag_default
    external: true

Docker socket volume

Since Portainer needs to be able to read and modify the state of the Docker engine, it requires access to the Docker socket file. This is mounted just like any other volume:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Persistent data

Portainer stores some persistent data. In the Docker container, this is located at /data, so we mount a Docker volume there:

    volumes:
      - /srv/portainer/data:/data

Configuration

All configuration is done within Portainer itself. It has a complete settings interface.

Single Sign On with Authentik

Portainer has the ability to interface with an OpenID Connect provider like Authentik.

Configuring SSO in Portainer

The relevant settings are confiured in the Authentication section of the Settings interface. Select the OAuth card for the Authentication method option. See the following table for the rest of the settings:

Option Value Description
Use SSO Enable single sign-on
Hide internal authentication prompt Only use SSO for logins, not Portainer's built-in system
Automatic user provisioning Automatically create new users when they first log in. This is safe if (1) you trust all users who can log in to Portainer using SSO, or (2) you don't give new users write access to resources in Portainer.
Automatic team membership Assign users to Teams based on the groups they belong to within Authentik
Claim name groups The claim in which Authentik places the list of groups
Statically assigned teams Whatever you want Use this field to map from Authentik groups to Portainer teams. You must create the team in Portainer before you can select it here.
Default team No team (or a read-only team) Don't assign normal users who aren't part of a privileged group to a team
Assign admin rights to groups Automatically assign administrator permissions to certain users
Admin mapping claim value regex Administrators Give members of the Administrators group admin permissions in Portainer

In the Provider section, select the Custom card. See the following table for the settings' values:

Option Value Description
Client ID Client ID created by Authentik Sets the OpenID client ID
Client Secret Client Secret created by Authentik Sets the OpenID client secret for authenticating with Authentik
Authorization URL https://auth2.kasad.com/application/o/authorize/ OpenID authorization endpoint
Access token URL https://auth2.kasad.com/application/o/token/ OpenID authorization endpoint
Resource URL https://auth2.kasad.com/application/o/userinfo/ OpenID user information resource endpoint
Redirect URL https://swag.kasad.com/portainer/ The URL Authentik will redirect t o after successful authentication
Logout URL https://auth2.kasad.com/if/session-end/portainer/ The URL Portainer will redirect to when logging out
User identifier sub or preferred_username Defines what field Portainer will use to map Portainer users to Authentik users. If usernames are controlled and static, it is safe to use preferred_username. Otherwise sub should be used, which is essentially a per-user UUID.
Scopes openid profile email The OpenID user info scopes that Portainer will request from Authentik

Configuring SSO in Authentik

On the Authentik side, an Application and an OpenID Provider must be created. For the Redirect URI option, use the base URL of the Portainer instance, in our case https://swag.kasad.com/portainer/. All other options should be fine when left with their default values.

Using Portainer

Stack environment variables

When defining environment variables for a Docker Compose stack in Portainer, the variables will be accessible within the docker compose file as if defined in a .env file when using the docker compose command.

The variables will also be written to a stack.env file, so they can be loaded into a container's environment be adding the following line to the service entry for that container:

    env_file: stack.env

Docker Compose build contexts

When building a container in a Docker Compose stack, it is not possible to use a path on the host as the build context (i.e. where the Dockerfile is located). This is different from defining volumes, which use paths on the host, not inside the Portainer container.

To get around this, either mount the build context path in the Portainer container, or use a non-file context like a Git repository.