Add Portainer stack and update paths to /opt/homarr

Changes: - Add portainer-stack.yml for easy Portainer deployment - Add PORTAINER.md with detailed Portainer instructions - Update docker-compose.yml to use /opt/homarr storage - Update .env.example with better comments - Update README.md with Portainer-first approach - All persistent data now at /opt/homarr
2026-02-03 10:50:33 +01:00 · 2026-02-03 10:50:33 +01:00 · 3ca7d4407e
parent 1f21a416c3
commit 3ca7d4407e
5 changed files with 356 additions and 83 deletions
--- a/.env.example
+++ b/.env.example
@ -1,35 +1,24 @@
 #======================================================================#
 #     Homarr Environment Configuration                                #
-#     Copy this file to .env and customize values                     #
+#     Storage: /opt/homarr                                            #
+#     Repo: git.lemonlink.eu/impulsivefps/homarr-dashboard            #
 #======================================================================#

 #------------------------------------------------------------------#
-# Repository Info                                                   #
+# Security (REQUIRED)                                               #
 #------------------------------------------------------------------#
-# Repo: gitea.lemonlink.eu/homelab/homarr-dashboard
-# Clone: git clone https://gitea.lemonlink.eu/homelab/homarr-dashboard.git
-
-#------------------------------------------------------------------#
-# Security                                                          #
-#------------------------------------------------------------------#
-# Generate a secure 64-character hex string for encryption
+# Generate a secure 64-character hex string:
 # PowerShell: -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
 # Linux/Mac: openssl rand -hex 32
-SECRET_ENCRYPTION_KEY=4edb53b70d198494e57ce5341aeb1edb384d808df740479aac8985fc36849aeb
-
-#------------------------------------------------------------------#
-# Port Configuration                                                #
-#------------------------------------------------------------------#
-# Change if ports are already in use
-HOMARR_PORT=7575
-DASH_PORT=3001
+SECRET_ENCRYPTION_KEY=CHANGE_ME_TO_64_CHAR_HEX_STRING

 #------------------------------------------------------------------#
 # Domain Configuration (for reference)                              #
 #------------------------------------------------------------------#
-# Configure these in NPM:
+# Configure these in Nginx Proxy Manager:
 # - dashboard.lemonlink.eu → http://homarr:7575
 # - system.lemonlink.eu → http://dash:3001
+#
 DOMAIN=lemonlink.eu
 DASHBOARD_SUBDOMAIN=dashboard
 SYSTEM_SUBDOMAIN=system
@ -42,22 +31,13 @@ AUTH_PROVIDERS=credentials

 #------------------------------------------------------------------#
 # OIDC Configuration (Optional)                                     #
-# Uncomment and configure if using OIDC/Authelia/Authentik          #
+# Uncomment if using Authelia/Authentik/Keycloak                    #
 #------------------------------------------------------------------#
 # AUTH_OIDC_URI=https://auth.lemonlink.eu
 # AUTH_OIDC_CLIENT_ID=homarr
 # AUTH_OIDC_CLIENT_SECRET=your-client-secret
 # AUTH_OIDC_CLIENT_NAME=Homarr

-#------------------------------------------------------------------#
-# LDAP Configuration (Optional)                                     #
-# Uncomment and configure if using LDAP/Active Directory            #
-#------------------------------------------------------------------#
-# AUTH_LDAP_URI=ldap://ldap.lemonlink.eu:389
-# AUTH_LDAP_BASE=dc=lemonlink,dc=eu
-# AUTH_LDAP_BIND_DN=cn=admin,dc=lemonlink,dc=eu
-# AUTH_LDAP_BIND_PASSWORD=your-ldap-password
-
 #------------------------------------------------------------------#
 # Dash. Configuration                                               #
 #------------------------------------------------------------------#
@ -70,23 +50,14 @@ DASH_SPEED_TEST_INTERVAL=240
 # Check interval in seconds (86400 = 24 hours)
 WATCHTOWER_INTERVAL=86400

-# Optional: Discord/Slack notifications
-# WATCHTOWER_NOTIFICATIONS=shoutrrr+discord://token@id
-
 #------------------------------------------------------------------#
-# Database                                                          #
+# Database & Logging                                                #
 #------------------------------------------------------------------#
-# SQLite (default) - no additional config needed
 DB_URL=/appdata/db/homarr.db
-
-#------------------------------------------------------------------#
-# Logging                                                           #
-#------------------------------------------------------------------#
 LOG_LEVEL=info
 NODE_ENV=production

 #------------------------------------------------------------------#
 # Analytics (Optional)                                              #
 #------------------------------------------------------------------#
-# Set to false to disable anonymous analytics
 ANALYTICS_ENABLED=true
--- a/PORTAINER.md
+++ b/PORTAINER.md
@ -0,0 +1,186 @@
+# 🐳 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
--- a/README.md
+++ b/README.md
@ -20,15 +20,16 @@ A complete, production-ready Homarr deployment with system monitoring, RSS feeds
 ```
 homarr-dashboard/
 ├── .git/                    # Gitea repository
-├── .env                     # Environment configuration (local only)
 ├── .env.example             # Environment template
 ├── .gitignore               # Git ignore rules
-├── docker-compose.yml       # Main deployment file
+├── docker-compose.yml       # Docker Compose file
+├── portainer-stack.yml      # Portainer stack file ⭐
 ├── deploy.sh                # Initial deployment script
-├── update.sh                # Update from Gitea script
+├── update.sh                # Update script
 ├── README.md                # This file
-├── DEPLOYMENT.md            # Complete deployment guide
-├── GITEA_SETUP.md           # Gitea repository setup
+├── PORTAINER.md             # Portainer deployment guide ⭐
+├── DEPLOYMENT.md            # General deployment guide
+├── GITEA_SETUP.md           # Gitea setup guide
 └── config/                  # Configuration files
    ├── apps.json            # 60+ pre-configured apps
    ├── rss-feeds.json       # Curated RSS feeds
@ -70,25 +71,57 @@ cd /opt/homelab/homarr-dashboard
 ./update.sh
 ```

-## 🚀 Quick Start (Without Git)
+## 🚀 Deploy with Portainer (Recommended)
+
+### Quick Setup

 ```bash
-# 1. Copy to your server
-cp -r homarr-deploy /opt/
-cd /opt/homarr-deploy
+# 1. SSH to your server and create directory
+ssh user@your-server
+sudo mkdir -p /opt/homarr
+sudo chown -R $USER:$USER /opt/homarr

-# 2. Configure environment
+# 2. Create environment file
+cat > /opt/homarr/.env << 'EOF'
+SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)
+AUTH_PROVIDERS=credentials
+DASH_SPEED_TEST_INTERVAL=240
+WATCHTOWER_INTERVAL=86400
+EOF
+
+# 3. Ensure NPM network exists
+docker network create npm-network 2>/dev/null || true
+```
+
+### In Portainer:
+
+1. **Stacks** → **Add Stack**
+2. **Name**: `homarr`
+3. **Build method**: Repository
+4. **Repository URL**: `https://git.lemonlink.eu/impulsivefps/homarr-dashboard.git`
+5. **Compose path**: `portainer-stack.yml`
+6. **Deploy**
+
+See [PORTAINER.md](PORTAINER.md) for detailed instructions.
+
+---
+
+## 🐳 Docker Compose (Alternative)
+
+```bash
+# 1. Clone repo
+git clone https://git.lemonlink.eu/impulsivefps/homarr-dashboard.git /opt/homarr
+cd /opt/homarr
+
+# 2. Configure
 cp .env.example .env
 # Edit .env with your settings

 # 3. Ensure NPM network exists
 docker network create npm-network 2>/dev/null || true

-# 4. Start services
+# 4. Deploy
 docker compose up -d
-
-# 5. Access dashboard
-# http://your-server-ip:7575
 ```

 ## 📋 What's Included
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -1,40 +1,30 @@
 #======================================================================#
-#     Homarr + Dash. - Ultimate Homelab Dashboard Stack               #
-#     Designed for Nginx Proxy Manager (NPM)                          #
-#     Repo: gitea.lemonlink.eu/homelab/homarr-dashboard               #
+#     Homarr + Dash. - Docker Compose                                 #
+#     Storage: /opt/homarr                                            #
+#     Repo: git.lemonlink.eu/impulsivefps/homarr-dashboard            #
 #======================================================================#

 services:
-  #------------------------------------------------------------------#
-  # Homarr 1.0 - Modern Dashboard                                    #
-  #------------------------------------------------------------------#
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:beta
    restart: unless-stopped
    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - ./homarr/appdata:/appdata
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /opt/homarr/appdata:/appdata
    environment:
-      # Generate with: openssl rand -hex 32
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-      # Database configuration (SQLite default)
      - DB_URL=/appdata/db/homarr.db
-      # Authentication settings
      - AUTH_PROVIDERS=${AUTH_PROVIDERS:-credentials}
-      # Logging
      - NODE_ENV=production
    ports:
      - '${HOMARR_PORT:-7575}:7575'
    networks:
-      - dashboard-network
-      - npm-network  # Connect to NPM network for reverse proxy
+      - homarr-network
+      - npm-network
    depends_on:
      - dash

-  #------------------------------------------------------------------#
-  # Dash. - System Monitoring                                        #
-  #------------------------------------------------------------------#
  dash:
    container_name: dash
    image: mauricenino/dashdot:latest
@ -43,14 +33,11 @@ services:
    volumes:
      - /:/mnt/host:ro
    environment:
-      # Widget customization
      - DASHDOT_ENABLE_CPU_TEMPS=true
      - DASHDOT_ALWAYS_SHOW_PERCENTAGES=true
      - DASHDOT_ENABLE_STORAGE_SPLIT_VIEW=true
      - DASHDOT_PAGE_TITLE=System Overview
-      # Network speed test (every 4 hours)
      - DASHDOT_SPEED_TEST_INTERVAL=${DASH_SPEED_TEST_INTERVAL:-240}
-      # Theme - dark to match lemonlink.eu
      - DASHDOT_WIDGET_LIST=os,cpu,storage,ram,network
      - DASHDOT_OS_LABEL_LIST=brand,os,arch,up_since
      - DASHDOT_CPU_LABEL_LIST=brand,model,cores,threads,frequency
@ -60,29 +47,26 @@ services:
    ports:
      - '${DASH_PORT:-3001}:3001'
    networks:
-      - dashboard-network
-      - npm-network  # Connect to NPM network for reverse proxy
+      - homarr-network
+      - npm-network

-  #------------------------------------------------------------------#
-  # Watchtower - Auto-update containers                              #
-  #------------------------------------------------------------------#
  watchtower:
    container_name: watchtower
    image: containrrr/watchtower:latest
    restart: unless-stopped
    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
+      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=${WATCHTOWER_INTERVAL:-86400}
      - WATCHTOWER_INCLUDE_STOPPED=true
-      - WATCHTOWER_NOTIFICATIONS=${WATCHTOWER_NOTIFICATIONS:-}
-    command: --interval ${WATCHTOWER_INTERVAL:-86400} homarr dash
+      - WATCHTOWER_LABEL_ENABLE=true
+    command: --interval ${WATCHTOWER_INTERVAL:-86400}
    networks:
-      - dashboard-network
+      - homarr-network

 networks:
-  dashboard-network:
+  homarr-network:
    driver: bridge
  npm-network:
-    external: true  # Created by NPM
+    external: true
--- a/portainer-stack.yml
+++ b/portainer-stack.yml
@ -0,0 +1,99 @@
+#======================================================================#
+#     Portainer Stack - Homarr Dashboard                              #
+#     Repo: git.lemonlink.eu/impulsivefps/homarr-dashboard            #
+#======================================================================#
+# 
+# Deploy instructions:
+# 1. In Portainer: Stacks → Add Stack
+# 2. Name: homarr
+# 3. Copy this file to Web Editor
+# 4. Ensure /opt/homarr directory exists on host
+# 5. Deploy the stack
+#
+# Storage location: /opt/homarr
+#------------------------------------------------------------------#
+
+version: '3.8'
+
+services:
+  #------------------------------------------------------------------#
+  # Homarr 1.0 - Modern Dashboard                                    #
+  #------------------------------------------------------------------#
+  homarr:
+    container_name: homarr
+    image: ghcr.io/homarr-labs/homarr:beta
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /opt/homarr/appdata:/appdata
+    environment:
+      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
+      - DB_URL=/appdata/db/homarr.db
+      - AUTH_PROVIDERS=${AUTH_PROVIDERS:-credentials}
+      - NODE_ENV=production
+    ports:
+      - '7575:7575'
+    networks:
+      - homarr-network
+      - npm-network  # Connect to NPM for reverse proxy
+    depends_on:
+      - dash
+    labels:
+      - "com.homarr.description=Homarr Dashboard"
+
+  #------------------------------------------------------------------#
+  # Dash. - System Monitoring                                        #
+  #------------------------------------------------------------------#
+  dash:
+    container_name: dash
+    image: mauricenino/dashdot:latest
+    restart: unless-stopped
+    privileged: true
+    volumes:
+      - /:/mnt/host:ro
+    environment:
+      - DASHDOT_ENABLE_CPU_TEMPS=true
+      - DASHDOT_ALWAYS_SHOW_PERCENTAGES=true
+      - DASHDOT_ENABLE_STORAGE_SPLIT_VIEW=true
+      - DASHDOT_PAGE_TITLE=System Overview
+      - DASHDOT_SPEED_TEST_INTERVAL=${DASH_SPEED_TEST_INTERVAL:-240}
+      - DASHDOT_WIDGET_LIST=os,cpu,storage,ram,network
+      - DASHDOT_OS_LABEL_LIST=brand,os,arch,up_since
+      - DASHDOT_CPU_LABEL_LIST=brand,model,cores,threads,frequency
+      - DASHDOT_STORAGE_LABEL_LIST=brand,size,type
+      - DASHDOT_RAM_LABEL_LIST=brand,size,type,frequency
+      - DASHDOT_NETWORK_LABEL_LIST=type,speed_up,speed_down,interface_speed
+    ports:
+      - '3001:3001'
+    networks:
+      - homarr-network
+      - npm-network
+    labels:
+      - "com.homarr.description=System Monitor"
+
+  #------------------------------------------------------------------#
+  # Watchtower - Auto-update containers                              #
+  #------------------------------------------------------------------#
+  watchtower:
+    container_name: watchtower
+    image: containrrr/watchtower:latest
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      - WATCHTOWER_CLEANUP=true
+      - WATCHTOWER_POLL_INTERVAL=${WATCHTOWER_INTERVAL:-86400}
+      - WATCHTOWER_INCLUDE_STOPPED=true
+      - WATCHTOWER_LABEL_ENABLE=true  # Only update containers with specific label
+    command: --interval ${WATCHTOWER_INTERVAL:-86400}
+    networks:
+      - homarr-network
+    labels:
+      - "com.centurylinklabs.watchtower.enable=true"
+
+networks:
+  homarr-network:
+    driver: bridge
+  npm-network:
+    external: true  # Created by Nginx Proxy Manager
+    name: npm-network