187 lines
4.3 KiB
Markdown
187 lines
4.3 KiB
Markdown
# 🐳 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
|