124-webapp/PORTAINER_QUICKREF.md

# Portainer Quick Reference

## 🚀 Quick Start

### Access Portainer
```
http://localhost:9000
or
http://einszwovier.local:9000
```

### First Login
1. Create admin account
2. Select "Local" environment
3. Done!

## 📊 Stack Overview: studio-einszwovier

| Service | Port | Health Check | Purpose |
|---------|------|--------------|---------|
| web | 80 | ✅ | PDF Cost Calculator |
| bookstack | 6875 | ✅ | Documentation Wiki |
| bookstack-mariadb | - | ✅ | Database |
| synapse | 8008 | ✅ | Matrix Server |
| ollama | 11434 | ✅ | Local LLM |
| open-webui | 8080 | ✅ | LLM Interface |
| watchtower | - | ✅ | Auto-Updates |
| portainer | 9000 | ✅ | Management UI |

## 🎯 Common Tasks

### View All Services
**Portainer**: Stacks → studio-einszwovier
**CLI**: `docker-compose ps`

### Restart a Service
**Portainer**: Containers → [service] → Restart
**CLI**: `docker-compose restart [service]`

### View Logs
**Portainer**: Containers → [service] → Logs
**CLI**: `docker-compose logs -f [service]`

### Check Health Status
**Portainer**: Containers → Look for 🟢/🔴 indicator
**CLI**: `docker-compose ps` (shows (healthy) or (unhealthy))

### Stop Everything
**Portainer**: Stacks → studio-einszwovier → Stop
**CLI**: `docker-compose stop`

### Start Everything
**Portainer**: Stacks → studio-einszwovier → Start
**CLI**: `docker-compose start`

### Update a Service
**Portainer**: Containers → [service] → Recreate
**CLI**: `docker-compose pull [service] && docker-compose up -d [service]`

## 🔍 Troubleshooting

### Service Shows 🔴 Unhealthy
1. Click container → Logs
2. Look for errors
3. Check health check output in Inspect tab
4. Restart if needed

### Can't Access Portainer
```bash
docker-compose restart portainer
# Wait 30 seconds
# Try again at http://localhost:9000
```

### Service Won't Start
1. Check Portainer logs for the service
2. Look for dependency issues (red containers)
3. Check resource limits (Stats tab)
4. Verify environment variables in Container → Env

## 📋 Health Check Endpoints

Test manually if needed:

```bash
# Web App
curl http://localhost/

# BookStack
curl http://localhost:6875/

# Matrix Synapse
curl http://localhost:8008/health

# Ollama
curl http://localhost:11434/api/tags

# Open WebUI
curl http://localhost:8080/

# Portainer
curl http://localhost:9000/api/system/status
```

## 🏷️ Labels in Portainer

All services are tagged with:
- **description**: What it does
- **maintainer**: Studio EinsZwoVier
- **watchtower.enable**: Auto-update enabled

Filter by labels in Portainer UI!

## 🔄 Auto-Updates (Watchtower)

- **Schedule**: Every 24 hours
- **Action**: Pulls latest images and recreates containers
- **Which services**: Only those with `watchtower.enable=true` label
- **View updates**: Containers → watchtower → Logs

### Disable Auto-Update for a Service
Edit docker-compose.yml, remove:
```yaml
labels:
  - "com.centurylinklabs.watchtower.enable=true"
```

## 📈 Resource Monitoring

**Portainer**: Container → Stats
Shows:
- CPU usage (%)
- Memory usage (MB / GB)
- Network I/O
- Block I/O

**Limits Set**:
- web: 1GB RAM, 1 CPU
- ollama: 8GB RAM, 4 CPU

## 🌐 Network: einszwovier_network

All services communicate on this network.

**View**: Networks → einszwovier_network → Connected containers

## 💾 Volumes

| Volume | Used By | Purpose |
|--------|---------|---------|
| portainer_data | portainer | Portainer config |
| ./data/uploads | web | PDF uploads |
| ./bookstack/* | bookstack | Wiki data |
| ./matrix/data | synapse | Matrix data |
| ./ollama | ollama | LLM models |
| ./open-webui | open-webui | Chat history |

**Backup**: See `backup.sh` script

## ⚙️ Useful Portainer Features

### Execute Shell Commands
1. Containers → [service] → Console
2. Select `/bin/bash` or `/bin/sh`
3. Click Connect
4. Run commands

### View Container Config
1. Containers → [service] → Inspect
2. See full JSON configuration
3. Copy environment variables
4. Check volume mounts

### Duplicate Container
1. Containers → [service] → Duplicate/Edit
2. Modify settings
3. Deploy as new container

### Container Template
1. App Templates → Custom Templates
2. Create from existing container
3. Reuse configuration

## 🎨 Status Icons

| Icon | Meaning | Action |
|------|---------|--------|
| 🟢 | Healthy | None needed |
| 🟡 | Starting | Wait (within start_period) |
| 🔴 | Unhealthy | Check logs |
| ⚫ | Stopped | Start container |
| 🔄 | Restarting | Wait or investigate |

## 📞 Quick Help

### "I can't find my containers!"
- Go to **Home**
- Select **Local** environment
- Go to **Stacks** → studio-einszwovier

### "Health checks keep failing"
- Increase `start_period` in docker-compose.yml
- Check service logs for actual errors
- Verify network connectivity

### "Portainer shows wrong status"
- Refresh page (F5)
- Check "Last Updated" timestamp
- Restart Portainer if stale

## 🔐 Security Notes

- Portainer admin password is set on first login (save it!)
- Docker socket mounted = full control (use carefully)
- HTTPS available on port 9443 (configure in Portainer settings)

## 📱 Mobile Access

Portainer works great on mobile:
1. Open browser on phone
2. Navigate to `http://[server-ip]:9000`
3. Same features as desktop!

## ✅ Daily Checklist

- [ ] All services showing 🟢 healthy
- [ ] No unusual CPU/memory spikes
- [ ] Recent watchtower update logs look good
- [ ] No red error logs in critical services

**Portainer makes this a 30-second check!**