# 7: Portainer - Docker Management Platform

Portainer CE (Community Edition) provides a web-based management interface for Docker environments. It offers container lifecycle management, stack deployment, image/volume/network management, resource monitoring, and role-based access control. For advanced features, API documentation, and enterprise features, see the [official Portainer documentation](https://docs.portainer.io/).

## Prerequisites

- ✅ **Docker installed** (Chapter 3)
- ✅ **Docker Compose** (Chapter 3)
- ✅ **Optional: Traefik installed** (Chapter 4) for HTTPS with Let's Encrypt
- ✅ **Optional: Domain configured** (Chapter 4.5), e.g., `portainer.example.com`

## Installation via Infinity Tools

### Menu Installation

```
📱 APPLICATIONS → Portainer → Install
```

### CLI Installation

```
sudo bash /opt/InfinityTools/Solutions/setup-portainer.sh --install

# With domain (Traefik mode)
export PORTAINER_DOMAIN="portainer.example.com"
sudo -E bash /opt/InfinityTools/Solutions/setup-portainer.sh --install
```

## Deployment Modes

### Traefik Mode (Recommended)

Uses Traefik for SSL termination and domain routing:

- Automatic Let's Encrypt certificate provisioning
- Domain-based access: `https://portainer.example.com`
- Security headers configured via Traefik middleware
- Requires: Traefik running, DNS A record configured

### Standalone Mode

Direct HTTPS access with self-signed certificate:

- Access via: `https://SERVER_IP:9443`
- Self-signed SSL (browser warning on first access)
- No domain required
- Suitable for internal/development use

## Installation Process

### Configuration Steps

1. **SSL Mode Selection:** Choose Traefik or Standalone
2. **If Traefik:** Provide domain name (e.g., `portainer.example.com`)
3. **If Standalone:** Specify HTTPS port (default: 9443)
4. **Network Detection:** Automatically detects Traefik network if available

### What Gets Created

- **Directory:** `/opt/speedbits/portainer`
- **Container:** `portainer` (portainer/portainer-ce:2.21.4)
- **Data Volume:** `/opt/speedbits/portainer/data`
- **Docker Compose:** `/opt/speedbits/portainer/docker-compose.yml`
- **Network:** Joins Traefik network (Traefik mode) or creates internal network (Standalone)

## First-Time Setup

### Admin Account Creation

**⚠️ CRITICAL:** Portainer requires admin credential creation on first access. No default credentials exist.

1. Access Portainer via the provided URL
2. Create administrator account: 
    - Username: Any (typically "admin")
    - Password: Minimum 12 characters (enforced)
3. Select Docker environment
4. Connect to local Docker socket

### Password Recovery

If admin password is lost, reset requires:

```
cd /opt/speedbits/portainer
docker compose down
rm -rf data/
docker compose up -d
```

**Note:** This resets all Portainer configuration (users, settings, RBAC). Docker containers are unaffected.

## Service Endpoints

- **Traefik mode:** `https://portainer.example.com`
- **Standalone mode:** `https://SERVER_IP:9443`
- **Internal API:** Portainer exposes port 9000 internally (mapped via Traefik or directly)

## Key Features

### Container Management

- Lifecycle operations (start/stop/restart/remove)
- Log viewing and streaming
- Container inspection (env vars, mounts, networks)
- Console access (exec into containers)
- Resource limits and constraints

### Stack Deployment

- Deploy docker-compose stacks via web UI
- Edit stack configurations
- Update and rollback stacks
- Environment variable management

### Image Management

- Browse local images
- Pull from registries (Docker Hub, private registries)
- Remove unused images
- Image tagging and management

### Volume and Network Management

- Create/manage Docker volumes
- Network configuration and inspection
- Volume backup considerations

### Monitoring and Statistics

- Real-time resource usage (CPU, memory, network)
- Container health status
- Historical performance data
- Event logs

## Security Configuration

### Initial Security

- ✅ Strong admin password (20+ characters recommended)
- ✅ Enable 2FA: Settings → Users → Two-Factor Authentication
- ✅ Use Traefik mode for production (Let's Encrypt SSL)
- ✅ Security headers configured via Traefik middleware (Traefik mode)

### Role-Based Access Control (RBAC)

- Create team members with restricted access
- Assign roles (admin, operator, viewer)
- Environment-level permissions
- Audit logging

### Backup Configuration

- Export Portainer settings: Settings → Backup Configuration
- Regular backups recommended
- Backup includes: users, roles, settings, stack definitions
- Does NOT include: Docker container data (managed separately via Borgmatic)

## Integration with Infinity Tools

Portainer complements Infinity Tools by providing:

- Visual management of Infinity Tools containers
- Log access for troubleshooting
- Resource monitoring for capacity planning
- Stack deployment for custom applications

**Note:** Infinity Tools applications are managed via their respective setup scripts. Portainer provides visibility and operational control, but configuration changes should be made through Infinity Tools scripts to maintain consistency.

## Troubleshooting

### Container Not Starting

```
docker logs portainer
docker ps -a | grep portainer
```

### Traefik Routing Issues

- Verify Traefik is running: `docker ps | grep traefik`
- Check Traefik logs: `docker logs traefik`
- Verify DNS resolution: `dig portainer.example.com`
- Confirm SSL certificate: Check Traefik dashboard or logs

### Docker Socket Access

Portainer requires read-only access to `/var/run/docker.sock`. The setup script configures this automatically. If issues occur:

```
ls -l /var/run/docker.sock
docker ps  # Verify Docker is accessible
```

## Production Considerations

- **High Availability:** Portainer CE is single-instance. For HA, consider Portainer Business Edition
- **Backup Strategy:** Regular Portainer config exports + Borgmatic for container data
- **Access Control:** Implement RBAC for team members
- **Network Security:** Use Traefik with firewall rules restricting access
- **Monitoring:** Integrate with monitoring solutions (Netdata, Uptime Kuma)

## Next Steps

Portainer is now operational. Use it to:

- Monitor Infinity Tools containers
- Deploy additional Docker applications
- Manage Docker resources
- Troubleshoot container issues

For advanced Portainer features, team management, and enterprise capabilities, refer to the [official Portainer documentation](https://docs.portainer.io/).