From 3ca7d4407ed4c0a727724b9da96717db4862c59e Mon Sep 17 00:00:00 2001 From: ImpulsiveFPS Date: Tue, 3 Feb 2026 10:50:33 +0100 Subject: [PATCH] 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 --- .env.example | 47 +++-------- PORTAINER.md | 186 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 61 +++++++++++---- docker-compose.yml | 46 ++++------- portainer-stack.yml | 99 +++++++++++++++++++++++ 5 files changed, 356 insertions(+), 83 deletions(-) create mode 100644 PORTAINER.md create mode 100644 portainer-stack.yml diff --git a/.env.example b/.env.example index aa11530..d692a52 100644 --- 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 diff --git a/PORTAINER.md b/PORTAINER.md new file mode 100644 index 0000000..13ddcc7 --- /dev/null +++ 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 diff --git a/README.md b/README.md index 5685d78..c78ab68 100644 --- 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 diff --git a/docker-compose.yml b/docker-compose.yml index 7a6a04b..035914a 100644 --- 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 diff --git a/portainer-stack.yml b/portainer-stack.yml new file mode 100644 index 0000000..e0fd9e1 --- /dev/null +++ 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