Skip to main content

⚓ Portainer (Community Edition)

Portainer is a lightweight web UI for managing Docker environments and containers. This guide shows a simple Docker Compose setup for Raspberry Pi, plus tips for security, backups and troubleshooting.

✅ Prerequisites​

  • Raspberry Pi with Docker installed (and Docker Compose)
  • SSH or local terminal access
  • Basic knowledge of Docker and networking

📁 Create directory and docker-compose.yml​

On your Pi run:

mkdir -p ~/docker/appdata/portainer
cd ~/docker/appdata/portainer
nano docker-compose.yml

Add the following to docker-compose.yml:

version: "3.8"
services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9443:9443" # Portainer web UI (HTTPS)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Access to Docker daemon
      - portainer_data:/data # Persist Portainer data

volumes:
  portainer_data:

Save and exit (Ctrl+X, Y, ENTER).

🚀 Start Portainer​

Start the stack:

docker compose up -d

Check status and logs:

docker ps -a
docker logs -f portainer

Stop and remove:

docker compose down

Update Portainer:

docker compose pull
docker compose up -d

🌐 Access the UI​

Open your browser to:

https://PI-IP:9443

  • Create the admin user on first run.
  • Portainer defaults to HTTPS; your browser may warn about a self-signed cert.

🔒 Security recommendations​

  • The Docker socket grants full control of the host — only run Portainer on trusted hosts.
  • Limit access using firewall rules, VPN, or a reverse proxy.
  • Use a reverse proxy (nginx, Traefik) with a valid TLS certificate (Let's Encrypt) for external access.
  • Keep Portainer and the host system updated.
  • Use strong admin credentials and enable 2FA if available.

Example minimal reverse proxy note:

  • Run Portainer without exposing port 9443 externally (bind to localhost) and let your reverse proxy handle TLS and authentication.

💾 Backup and restore​

  • Backup Portainer data volume:
docker run --rm -v portainer_data:/data -v "$(pwd)":/backup alpine \
  tar czf /backup/portainer_data.tar.gz -C /data .
  • Restore:
docker run --rm -v portainer_data:/data -v "$(pwd)":/backup alpine \
  sh -c "cd /data && tar xzf /backup/portainer_data.tar.gz"

Also export important configs via the Portainer UI when needed.

🔧 Troubleshooting​

  • No UI access:

    • Ensure the container is running: docker ps
    • Check firewall (ufw/iptables) and that port 9443 is reachable.
    • Verify the Docker socket exists: /var/run/docker.sock.

  • Permission issues accessing Docker socket:

    • Ensure the host has the socket and Docker is running.
    • Avoid changing socket permissions broadly; prefer controlling access via users/groups.

  • View logs for details:

docker logs portainer
docker compose logs -f

⚙️ Advanced tips​

  • Use Portainer Agent to manage multiple hosts securely.
  • Create a dedicated management VLAN or network for administration.
  • Use role-based access control (RBAC) to limit user permissions.
  • Integrate with LDAP/AD if managing many users.

Portainer makes container management easier — but remember: access to the Docker socket is powerful. Secure the host, restrict access, and keep regular backups.