# 🐳 Portainer Stack Deployment Guide

Deploy Homarr using Portainer's stack feature with persistent storage at `/opt/homarr`.

## 📋 Prerequisites

- Portainer CE/EE running
- `/opt/homarr` directory created on host
- Nginx Proxy Manager (for reverse proxy)
- `npm-network` created by NPM

---

## 🚀 Quick Deploy

### Step 1: Prepare Host Directory

SSH into your server and create the directory:

```bash
# Create storage directory
sudo mkdir -p /opt/homarr
sudo chown -R $USER:$USER /opt/homarr

# Ensure npm-network exists
docker network create npm-network 2>/dev/null || echo "Network already exists"
```

### Step 2: Create Environment File

```bash
# Create .env file
cat > /opt/homarr/.env << 'EOF'
SECRET_ENCRYPTION_KEY=YOUR_GENERATED_KEY_HERE
AUTH_PROVIDERS=credentials
DASH_SPEED_TEST_INTERVAL=240
WATCHTOWER_INTERVAL=86400
EOF

# Generate key if needed
openssl rand -hex 32
# Or PowerShell: -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
```

### Step 3: Deploy in Portainer

1. Open Portainer: `https://portainer.lemonlink.eu`
2. Navigate to: **Stacks** → **Add Stack**
3. Configure:
   - **Name**: `homarr`
   - **Build method**: Web editor
   - **Web editor**: Copy contents of `portainer-stack.yml`
4. Click **Deploy the stack**

### Step 4: Configure NPM

Add Proxy Hosts in Nginx Proxy Manager:

#### Dashboard (Homarr)
| Setting | Value |
|---------|-------|
| Domain Names | `dashboard.lemonlink.eu` |
| Scheme | `http` |
| Forward Hostname/IP | `homarr` |
| Forward Port | `7575` |
| Cache Assets | ✅ |
| Block Common Exploits | ✅ |

**SSL Tab:**
- Request SSL certificate
- Force SSL: ✅
- HTTP/2: ✅

#### System Monitor (Dash.)
| Setting | Value |
|---------|-------|
| Domain Names | `system.lemonlink.eu` |
| Forward Hostname/IP | `dash` |
| Forward Port | `3001` |

---

## 📁 Storage Structure

After deployment, files will be at:

```
/opt/homarr/
├── appdata/                 # Homarr configuration & database
│   ├── db/
│   │   └── homarr.db
│   └── ...
└── .env                     # Environment variables (you created)
```

---

## 🔄 Updating via Portainer

### Method 1: Portainer UI

1. Go to: **Stacks** → **homarr**
2. Click **Editor** tab
3. Update image tags if needed:
   - `ghcr.io/homarr-labs/homarr:beta` → `ghcr.io/homarr-labs/homarr:latest`
4. Click **Update the stack**
5. Select **Re-pull image and redeploy**

### Method 2: Git Integration (Recommended)

1. In Portainer: **Stacks** → **Add Stack**
2. **Build method**: Repository
3. Configure:
   - **Repository URL**: `https://git.lemonlink.eu/impulsivefps/homarr-dashboard.git`
   - **Repository reference**: `refs/heads/main`
   - **Compose path**: `portainer-stack.yml`
   - **Authentication**: (if private repo) Add username/token
4. Enable **Automatic updates** (optional)
5. Deploy

### Method 3: Manual Pull

```bash
# SSH to server
docker pull ghcr.io/homarr-labs/homarr:beta
docker pull mauricenino/dashdot:latest

# In Portainer: Restart the stack
```

---

## 🛠️ Troubleshooting

### Container won't start (permissions)

```bash
# Fix permissions
sudo chown -R 1000:1000 /opt/homarr
sudo chmod -R 755 /opt/homarr
```

### npm-network not found

```bash
# Create network
docker network create npm-network

# Or in Portainer: Networks → Add Network
# Name: npm-network, Driver: bridge
```

### Environment variables not loading

Portainer stacks don't automatically load `.env` files. You have two options:

**Option A**: Set variables in Portainer UI:
1. Stack → Editor → "Environment variables" section
2. Add each variable from `.env`

**Option B**: Hardcode in stack file (less secure)

### Data not persisting

Check volume mounts in Portainer:
1. Container → homarr → Volumes
2. Verify: `/opt/homarr/appdata` → `/appdata`

---

## 📊 Stack Overview

| Container | Image | Port | Purpose |
|-----------|-------|------|---------|
| homarr | homarr-labs/homarr:beta | 7575 | Dashboard |
| dash | mauricenino/dashdot:latest | 3001 | System Monitor |
| watchtower | containrrr/watchtower:latest | - | Auto-updates |

---

## 🔗 Useful Links

- **Dashboard**: https://dashboard.lemonlink.eu
- **System Monitor**: https://system.lemonlink.eu
- **Portainer**: https://portainer.lemonlink.eu
- **Git Repo**: https://git.lemonlink.eu/impulsivefps/homarr-dashboard