Portainer Installation Guide

Portainer Logo

A complete guide to deploying Portainer Community Edition - a lightweight management UI for Docker environments.

Prerequisites

Installation Methods

# Create volume for persistent data
docker volume create portainer_data

# Run Portainer container
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

Option 2: Docker Compose

Create docker-compose.yml:

version: '3'

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

volumes:
  portainer_data:

Then deploy with:

docker compose up -d

First-Time Setup

  1. Access the web UI:

    https://your-server-ip:9443
  2. Create admin user when prompted

  3. Select environment type:

    • Choose "Docker" for local management

    • Choose "Agent" for remote Docker hosts

Key Features Configuration

Adding Remote Docker Hosts

  1. Navigate to Environments

  2. Click Add environment

  3. Select Docker Standalone

  4. Enter connection details:

    • Name: Your server name

    • Environment URL: tcp://<remote-ip>:2375

    • (Requires Docker API access configured)

Setting Up Stacks

  1. Navigate to Stacks

  2. Click Add stack

  3. Provide:

    • Stack name

    • Web editor or upload method

    • Your compose file content

Maintenance

Backup Portainer Data

docker stop portainer
docker run --rm \
  -v portainer_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/portainer-backup-$(date +%Y%m%d).tar.gz -C /data .
docker start portainer

Update Portainer

docker stop portainer
docker rm portainer
docker pull portainer/portainer-ce:latest
# Re-run your original run command

Security Recommendations

  1. Always use HTTPS (Portainer defaults to 9443 with self-signed cert)

  2. Set up authentication:

    • Navigate to Users

    • Create individual accounts for team members

  3. Configure session timeout:

    • Settings → Authentication → Session timeout

  4. Restrict Docker API access:

    # Edit/create /etc/docker/daemon.json
    {
      "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2375"]
    }

Troubleshooting

Issue
Solution

"Unable to connect" error

Verify docker.sock volume mount

Login loop

Clear browser cache or try private mode

404 errors

Ensure using HTTPS on port 9443

Permission denied

Check Docker socket permissions (/var/run/docker.sock)

Pro Tip: For production environments, consider using Portainer Business Edition with additional features and support.


Final Notes:

Last updated