homarr-dashboard/PORTAINER.md

🐳 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:

# 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

# 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

# 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)

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

npm-network not found

# 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