Installing Portainer

Chapter objectives

Install Portainer on Docker standalone
Deploy Portainer on Docker Swarm
Configure the Portainer agent
Secure the installation

1 - Installation on Docker Standalone

Quick method

# Créer le volume de données
docker volume create portainer_data

# Déployer Portainer CE
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

Explanation of the parameters

Parameter	Description
`-p 9443:9443`	HTTPS port of the web interface
`-p 8000:8000`	Port for the Edge agent
`--restart=always`	Automatic restart
`-v /var/run/docker.sock`	Access to the Docker daemon
`-v portainer_data:/data`	Data persistence

With Docker Compose

# docker-compose.yml
version: "3.9"

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

docker compose up -d

First access

Open https://localhost:9443
Accept the self-signed certificate
Create the administrator account (strong password)
Select "Get Started" for the local environment

2 - Installation on Docker Swarm

Deployment as a service

# Sur un manager Swarm
docker service create \
  --name portainer \
  --publish 9443:9443 \
  --publish 8000:8000 \
  --replicas=1 \
  --constraint 'node.role==manager' \
  --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
  --mount type=volume,src=portainer_data,dst=/data \
  portainer/portainer-ce:latest

With a Stack (recommended)

# portainer-stack.yml
version: "3.9"

services:
  agent:
    image: portainer/agent:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    networks:
      - agent_network
    deploy:
      mode: global
      placement:
        constraints:
          - node.platform.os == linux

  portainer:
    image: portainer/portainer-ce:latest
    command: -H tcp://tasks.agent:9001 --tlsskipverify
    ports:
      - "9443:9443"
      - "8000:8000"
    volumes:
      - portainer_data:/data
    networks:
      - agent_network
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager

networks:
  agent_network:
    driver: overlay
    attachable: true

volumes:
  portainer_data:

docker stack deploy -c portainer-stack.yml portainer

Verification

# Services déployés
docker service ls | grep portainer

# Logs
docker service logs portainer_portainer

3 - Portainer agent

Why the agent?

The Portainer agent allows you to:

Manage remote environments
Access advanced features (browse volumes)
Avoid exposing the Docker socket

┌─────────────────────────────────────────────────────────────┐
│                   Portainer Server                           │
│                    (Centralisé)                              │
└──────────────────────────┬──────────────────────────────────┘
                           │ Port 9001
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
     ┌─────────┐      ┌─────────┐      ┌─────────┐
     │  Agent  │      │  Agent  │      │  Agent  │
     │ Host 1  │      │ Host 2  │      │ Host 3  │
     └─────────┘      └─────────┘      └─────────┘

Deploy the agent (standalone)

docker run -d \
  -p 9001:9001 \
  --name portainer_agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:latest

Deploy the agent (Swarm)

docker service create \
  --name portainer_agent \
  --network portainer_agent_network \
  --mode global \
  --constraint 'node.platform.os==linux' \
  --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
  --mount type=bind,src=/var/lib/docker/volumes,dst=/var/lib/docker/volumes \
  portainer/agent:latest

Connect the agent to Portainer

In Portainer, go to Environments
Click on Add environment
Select Agent
Enter: <IP_AGENT>:9001
Name the environment
Click on Connect

4 - Edge Agent

Use case

The Edge Agent is useful for:

Environments behind NAT/firewall
Outbound connection only
Remote sites without a public IP

Deployment

In Portainer, create an Edge environment
Copy the generated command
Run it on the remote host:

docker run -d \
  --name portainer_edge_agent \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -v portainer_agent_data:/data \
  -e EDGE=1 \
  -e EDGE_ID=<EDGE_ID> \
  -e EDGE_KEY=<EDGE_KEY> \
  -e EDGE_INSECURE_POLL=1 \
  portainer/agent:latest

5 - Advanced configuration

Environment variables

docker run -d \
  -p 9443:9443 \
  --name portainer \
  -e ADMIN_PASSWORD='$2y$...' \  # Hash bcrypt du mot de passe
  -e LOGO_URL='https://example.com/logo.png' \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Variable	Description
`ADMIN_PASSWORD`	bcrypt hash of the admin password
`LOGO_URL`	URL of the custom logo
`TEMPLATES_URL`	URL of the custom templates

Generate the password hash

# Avec htpasswd
htpasswd -nbB admin 'votre-mot-de-passe' | cut -d ":" -f 2

# Ou avec Docker
docker run --rm httpd:alpine htpasswd -nbB admin 'votre-mot-de-passe' | cut -d ":" -f 2

HTTPS with a custom certificate

docker run -d \
  -p 9443:9443 \
  --name portainer \
  -v /path/to/certs:/certs \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest \
  --ssl \
  --sslcert /certs/cert.pem \
  --sslkey /certs/key.pem

6 - Installation with Traefik

Docker Compose with Traefik

version: "3.9"

services:
  traefik:
    image: traefik:v2.10
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "[email protected]"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt

  portainer:
    image: portainer/portainer-ce:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.portainer.rule=Host(`portainer.example.com`)"
      - "traefik.http.routers.portainer.entrypoints=websecure"
      - "traefik.http.routers.portainer.tls.certresolver=le"
      - "traefik.http.services.portainer.loadbalancer.server.port=9000"

volumes:
  portainer_data:
  letsencrypt:

7 - Updating Portainer

Standalone

# Arrêter et supprimer le conteneur
docker stop portainer
docker rm portainer

# Télécharger la nouvelle image
docker pull portainer/portainer-ce:latest

# Redéployer (les données sont dans le 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

Swarm

# Mettre à jour le service
docker service update \
  --image portainer/portainer-ce:latest \
  portainer_portainer

# Mettre à jour l'agent
docker service update \
  --image portainer/agent:latest \
  portainer_agent

8 - Troubleshooting

Portainer does not start

# Vérifier les logs
docker logs portainer

# Vérifier le socket Docker
ls -la /var/run/docker.sock

# Permissions du socket
sudo chmod 666 /var/run/docker.sock

Unable to connect

# Vérifier que le conteneur tourne
docker ps | grep portainer

# Vérifier les ports
docker port portainer

# Tester la connectivité
curl -k https://localhost:9443

Reset the admin password

# Arrêter Portainer
docker stop portainer

# Réinitialiser
docker run --rm -v portainer_data:/data portainer/helper-reset-password

# Redémarrer
docker start portainer

Summary

Mode	Key command
Standalone	`docker run ... portainer/portainer-ce`
Swarm	`docker stack deploy` with agent
Agent	`docker run ... portainer/agent`
Edge	Agent with outbound connection

Key points

Always create a volume for persistence
Use the agent for remote environments
HTTPS enabled by default on port 9443
Data survives updates

Practical exercises

Install Portainer on your local machine
Create a secure administrator account
Add a remote environment with the agent
Configure HTTPS with a custom certificate

← Introduction | User interface →

Chapter objectives​

1 - Installation on Docker Standalone​

Quick method​

Explanation of the parameters​

With Docker Compose​

First access​

2 - Installation on Docker Swarm​

Deployment as a service​

With a Stack (recommended)​

Verification​

3 - Portainer agent​

Why the agent?​

Deploy the agent (standalone)​

Deploy the agent (Swarm)​

Connect the agent to Portainer​

4 - Edge Agent​

Use case​

Deployment​

5 - Advanced configuration​

Environment variables​

Generate the password hash​

HTTPS with a custom certificate​

6 - Installation with Traefik​

Docker Compose with Traefik​

7 - Updating Portainer​

Standalone​

Swarm​

8 - Troubleshooting​

Portainer does not start​

Unable to connect​

Reset the admin password​

Summary​

Practical exercises​

Chapter objectives

1 - Installation on Docker Standalone

Quick method

Explanation of the parameters

With Docker Compose

First access

2 - Installation on Docker Swarm

Deployment as a service

With a Stack (recommended)

Verification

3 - Portainer agent

Why the agent?

Deploy the agent (standalone)

Deploy the agent (Swarm)

Connect the agent to Portainer

4 - Edge Agent

Use case

Deployment

5 - Advanced configuration

Environment variables

Generate the password hash

HTTPS with a custom certificate

6 - Installation with Traefik

Docker Compose with Traefik

7 - Updating Portainer

Standalone

Swarm

8 - Troubleshooting

Portainer does not start

Unable to connect

Reset the admin password

Summary

Practical exercises