env documentation

.env.example

@@ -2,10 +2,6 @@
 # Copy this file to .env and fill in your values: cp .env.example .env
 # NEVER commit .env to git!
 
-# ====================================
-# SYSTEM CONFIGURATION
-# ====================================
-
 # User and Group IDs (get with: id -u and id -g)
 PUID=1000
 PGID=1000
@@ -16,6 +12,11 @@ TZ=America/New_York
 # Server IP address
 SERVER_IP=192.168.1.100
 
+# Default credentials (used by multiple services for easier setup)
+DEFAULT_USER=admin
+DEFAULT_PASSWORD=changeme
+DEFAULT_EMAIL=admin@example.com
+
 # ====================================
 # DOMAIN & DNS CONFIGURATION
 # ====================================
@@ -28,8 +29,8 @@ DUCKDNS_TOKEN=your-duckdns-token
 DUCKDNS_SUBDOMAINS=yourdomain  # Without .duckdns.org
 
 # Let's Encrypt / ACME (for SSL certificates)
-ACME_EMAIL=your-email@example.com
+ACME_EMAIL=${DEFAULT_EMAIL}
-ADMIN_EMAIL=your-email@example.com  # Used for admin user account
+ADMIN_EMAIL=${DEFAULT_EMAIL}  # Used for admin user account
 
 # Cloudflare API (optional, for DNS challenge instead of DuckDNS)
 # CF_DNS_API_TOKEN=your-cloudflare-api-token
@@ -47,9 +48,9 @@ AUTHELIA_STORAGE_ENCRYPTION_KEY=generate-with-openssl-rand-hex-64
 # Authelia Admin Credentials
 # These will be auto-generated by setup-homelab.sh
 # DO NOT set these manually - they are generated during setup
-# AUTHELIA_ADMIN_USER=admin
+# AUTHELIA_ADMIN_USER=${DEFAULT_USER}
-# AUTHELIA_ADMIN_EMAIL=admin@example.com
+# AUTHELIA_ADMIN_EMAIL=${DEFAULT_EMAIL}
-# AUTHELIA_ADMIN_PASSWORD=auto-generated-password
+# AUTHELIA_ADMIN_PASSWORD=${DEFAULT_PASSWORD}
 
 # SMTP for Authelia Notifications (OPTIONAL)
 # If not configured, notifications are saved to file instead
@@ -101,14 +102,14 @@ PLEX_CLAIM=claim-xxxxxxxxxx
 
 # qBittorrent
 QBITTORRENT_USER=admin
-QBITTORRENT_PASS=changeme
+QBITTORRENT_PASS=${DEFAULT_PASSWORD}
 
 # ====================================
 # INFRASTRUCTURE SERVICES
 # ====================================
 
 # Pi-hole
-PIHOLE_PASSWORD=changeme
+PIHOLE_PASSWORD=${DEFAULT_PASSWORD}
 
 # Watchtower Notifications (optional)
 # If not set, Watchtower will still update containers but without notifications
@@ -123,52 +124,52 @@ PIHOLE_PASSWORD=changeme
 # MONITORING & DASHBOARDS
 # ====================================
 
-GRAFANA_ADMIN_PASSWORD=changeme
+GRAFANA_ADMIN_PASSWORD=${DEFAULT_PASSWORD}
 
 # ====================================
 # DEVELOPMENT TOOLS
 # ====================================
 
-CODE_SERVER_PASSWORD=changeme
+CODE_SERVER_PASSWORD=${DEFAULT_PASSWORD}
-CODE_SERVER_SUDO_PASSWORD=changeme
+CODE_SERVER_SUDO_PASSWORD=${DEFAULT_PASSWORD}
 
-JUPYTER_TOKEN=changeme
+JUPYTER_TOKEN=${DEFAULT_PASSWORD}
 
 # ====================================
 # DATABASES - GENERAL
 # ====================================
 
-POSTGRES_USER=postgres
+POSTGRES_USER=${DEFAULT_USER}
-POSTGRES_PASSWORD=changeme
+POSTGRES_PASSWORD=${DEFAULT_PASSWORD}
 POSTGRES_DB=homelab
 
-PGADMIN_EMAIL=admin@example.com
+PGADMIN_EMAIL=${DEFAULT_EMAIL}
-PGADMIN_PASSWORD=changeme
+PGADMIN_PASSWORD=${DEFAULT_PASSWORD}
 
 # ====================================
 # PRODUCTIVITY SERVICES
 # ====================================
 
 # Nextcloud
-NEXTCLOUD_ADMIN_USER=admin
+NEXTCLOUD_ADMIN_USER=${DEFAULT_USER}
-NEXTCLOUD_ADMIN_PASSWORD=changeme
+NEXTCLOUD_ADMIN_PASSWORD=${DEFAULT_PASSWORD}
-NEXTCLOUD_DB_PASSWORD=changeme
+NEXTCLOUD_DB_PASSWORD=${DEFAULT_PASSWORD}
-NEXTCLOUD_DB_ROOT_PASSWORD=changeme
+NEXTCLOUD_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD}
 
 # Gitea
-GITEA_DB_PASSWORD=changeme
+GITEA_DB_PASSWORD=${DEFAULT_PASSWORD}
 
 # WordPress
-WORDPRESS_DB_PASSWORD=changeme
+WORDPRESS_DB_PASSWORD=${DEFAULT_PASSWORD}
-WORDPRESS_DB_ROOT_PASSWORD=changeme
+WORDPRESS_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD}
 
 # BookStack
-BOOKSTACK_DB_PASSWORD=changeme
+BOOKSTACK_DB_PASSWORD=${DEFAULT_PASSWORD}
-BOOKSTACK_DB_ROOT_PASSWORD=changeme
+BOOKSTACK_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD}
 
 # MediaWiki
-MEDIAWIKI_DB_PASSWORD=changeme
+MEDIAWIKI_DB_PASSWORD=${DEFAULT_PASSWORD}
-MEDIAWIKI_DB_ROOT_PASSWORD=changeme
+MEDIAWIKI_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD}
 
 # ====================================
 # UTILITIES
@@ -176,17 +177,17 @@ MEDIAWIKI_DB_ROOT_PASSWORD=changeme
 
 # Bitwarden (Vaultwarden) Password Manager
 # Admin token: openssl rand -base64 48
-BITWARDEN_ADMIN_TOKEN=changeme-bitwarden-admin-token
+BITWARDEN_ADMIN_TOKEN=${DEFAULT_PASSWORD}
 BITWARDEN_SIGNUPS_ALLOWED=true  # Set to false after creating accounts
 BITWARDEN_INVITATIONS_ALLOWED=true
 SMTP_HOST=smtp.gmail.com
-SMTP_FROM=bitwarden@yourdomain.com
+SMTP_FROM=${DEFAULT_EMAIL}
 SMTP_PORT=587
 SMTP_SECURITY=starttls
 
 # Form.io
-FORMIO_JWT_SECRET=changeme
+FORMIO_JWT_SECRET=${DEFAULT_PASSWORD}
-FORMIO_DB_SECRET=changeme
+FORMIO_DB_SECRET=${DEFAULT_PASSWORD}
 
 # ====================================
 # HOMEPAGE DASHBOARD - API KEYS
@@ -217,6 +218,4 @@ HOMEPAGE_VAR_UPTIMEKUMA_SLUG=your-uptime-kuma-slug
 HOMEPAGE_VAR_OPENWEATHER_KEY=your-openweather-api-key
 HOMEPAGE_VAR_WEATHERAPI_KEY=your-weatherapi-key
 HOMEPAGE_VAR_UNIFI_USER=your-unifi-username
-HOMEPAGE_VAR_UNIFI_PASS=your-unifi-password
+HOMEPAGE_VAR_UNIFI_PASS=your-unifi-password
-
-# Add your own variables below

.github/copilot-instructions.md

@@ -356,6 +356,58 @@ ls -lh /opt/stacks/core/traefik/acme.json  # Should be 600 permissions
 ```
 Verify: DuckDNS token valid, `DUCKDNS_TOKEN` in `.env`, DNS propagation (wait 2-5 min), acme.json writable by Traefik
 
+### Stuck Processes and Resource Issues
+```bash
+# Check for stuck processes
+ps aux | grep -E "(copilot|vscode|node)" | grep -v grep
+
+# Monitor system resources
+top -b -n1 | head -20
+
+# Kill stuck processes (be careful!)
+kill -9 PID  # Replace PID with actual process ID
+
+# Check Docker container resource usage
+docker stats --no-stream
+
+# Clean up stopped containers
+docker container prune -f
+```
+
+### File Permission Issues
+```bash
+# Check file ownership
+ls -la /opt/stacks/stack-name/config/
+
+# Fix permissions for Docker volumes
+sudo chown -R 1000:1000 /opt/stacks/stack-name/config/
+
+# Validate PUID/PGID in .env
+echo "PUID: $PUID, PGID: $PGID"
+id -u && id -g  # Should match PUID/PGID
+
+# Check volume mount permissions
+docker run --rm -v /opt/stacks/stack-name/config:/test busybox ls -la /test
+```
+
+### System Health Checks
+```bash
+# Check Docker daemon status
+sudo systemctl status docker
+
+# Verify network connectivity
+ping -c 3 google.com
+
+# Check DNS resolution
+nslookup yourdomain.duckdns.org
+
+# Monitor disk space
+df -h
+
+# Check system load
+uptime && cat /proc/loadavg
+```
+
 ## AI Management Capabilities
 
 You can manage this homelab by:

README.md

@@ -33,7 +33,7 @@ sudo ./scripts/deploy-homelab.sh
 
 **Access your homelab:**
 - **Dockge**: `https://dockge.yourdomain.duckdns.org` (primary management interface)
-- **Homepage**: `https://home.yourdomain.duckdns.org` (service dashboard)
+- **Homepage**: `https://homepage.yourdomain.duckdns.org` (service dashboard)
 - **Authelia**: `https://auth.yourdomain.duckdns.org` (SSO login)
 
 ## 📚 Documentation

docs/ai-management-prompts.md

@@ -4,29 +4,35 @@ This guide provides example prompts you can use with GitHub Copilot to manage yo
 
 ## Container and Stack Management
 
-### Starting Services
+### Controling Services
-- "Start the media stack"
+- "Start/Pause/Stop/Restart the media stack"
-- "Deploy the monitoring services"
+- "Start/Pause/Stop/Restart wordpress"
-- "Launch the productivity applications"
+- "Deploy the monitoring stack"
 - "Bring up the core infrastructure"
 
-### Stopping Services
-- "Stop the media stack"
-- "Shut down the monitoring services"
-- "Pause the productivity applications"
-- "Take down the core infrastructure"
 
-### Restarting Services
+### Restarting a service vs restarting a stack
-- "Restart the media stack"
+
-- "Reload the monitoring services"
+Restarting a container (service) does NOT pick up changes to the compose file
-- "Reboot the productivity applications"
+
-- "Refresh the core infrastructure"
+Restarting a stack uses docker compose down && docker compose up -d  
+This DOES load changes to the compose file
+
+Restart traefik/sablier container(s) to apply configuration changes  
+Restart the core stack to apply changes to the compose file  
+
+Homepage configuration is loaded on demand, no restart needed
 
 ### Status Checks
+
+>If your server keeps locking up, it's likely stuck background processes.  
+VS Code Copilot Chat in Agent mode sometimes leaves a stuck process running (in my experience)
+
 - "Show me the status of all containers"
 - "Check if the media services are running"
 - "List all deployed stacks"
 - "Monitor container resource usage"
+- "Check for and close any stuck proccesses hogging system resources"
 
 ## Service Configuration
 
@@ -68,6 +74,28 @@ This guide provides example prompts you can use with GitHub Copilot to manage yo
 - "Verify network connectivity between services"
 - "Test SSL certificate validity"
 
+### System Health Checks
+- "Check for stuck processes consuming resources"
+- "Monitor system load and identify bottlenecks"
+- "Verify file permissions for Docker volumes"
+- "Check Docker daemon status and logs"
+- "Validate network connectivity and DNS resolution"
+- "Review system resource limits and quotas"
+
+### Stuck Process Investigation
+- "Find and terminate any stuck AI assistant processes"
+- "Check for runaway Docker containers"
+- "Monitor background jobs and cleanup if needed"
+- "Review system process table for anomalies"
+- "Check VS Code extension processes that may be hanging"
+
+### File Permission Issues
+- "Fix permission problems with Docker volumes"
+- "Set correct ownership for service configuration files"
+- "Resolve access denied errors for mounted directories"
+- "Validate PUID/PGID settings match system users"
+- "Check and repair file system permissions recursively"
+
 ## Backup and Recovery
 
 ### Creating Backups

docs/env-configuration.md

@@ -0,0 +1,221 @@
+# Environment Configuration Guide
+
+This guide explains how to configure the `.env` file required for your AI-Homelab deployment.
+
+## Prerequisites
+
+Before running the setup scripts, you must create and configure a `.env` file in the root of the repository.
+
+### Step 1: Copy the Example File
+
+```bash
+# Copy the example file to create your .env file
+cp .env.example .env
+```
+
+This ensures you have all the required variables with proper defaults and structure.
+
+### Step 2: Edit Your Configuration
+
+Open the newly created `.env` file and modify the values to match your setup:
+
+```bash
+# Edit the file with your preferred editor
+nano .env  # or use any text editor
+```
+
+## Required Variables
+
+The `.env` file contains the following key variables that you must configure:
+
+```bash
+# Domain Configuration
+DOMAIN=yourdomain.duckdns.org
+DUCKDNS_TOKEN=your-duckdns-token
+DUCKDNS_SUBDOMAINS=yourdomain
+
+# User Configuration (Linux user IDs)
+PUID=1000
+PGID=1000
+
+# Default Credentials (used by multiple services)
+DEFAULT_USER=admin
+DEFAULT_PASSWORD=changeme
+DEFAULT_EMAIL=admin@example.com
+
+# Timezone
+TZ=America/New_York
+
+# Authelia Secrets (auto-generated by setup script)
+AUTHELIA_JWT_SECRET=64-char-secret
+AUTHELIA_SESSION_SECRET=64-char-secret
+AUTHELIA_STORAGE_ENCRYPTION_KEY=64-char-secret
+
+# VPN Configuration (optional, for download services)
+SURFSHARK_PRIVATE_KEY=your-vpn-private-key
+```
+
+## Step-by-Step Configuration
+
+### 1. Domain Setup
+
+**DuckDNS Configuration:**
+1. Go to [duckdns.org](https://duckdns.org)
+2. Create an account and get your token
+3. Choose your subdomain (e.g., `yourname`)
+4. Your domain will be `yourname.duckdns.org`
+
+```bash
+DOMAIN=yourname.duckdns.org
+DUCKDNS_TOKEN=your-actual-token-here
+DUCKDNS_SUBDOMAINS=yourname
+```
+
+### 2. User IDs
+
+Get your Linux user and group IDs:
+
+```bash
+# Run these commands to get your IDs
+id -u  # This gives you PUID
+id -g  # This gives you PGID
+```
+
+Typically these are both `1000` for the first user.
+
+### 3. Default Credentials
+
+Set default credentials that will be used by multiple services for easier setup:
+
+```bash
+DEFAULT_USER=admin
+DEFAULT_PASSWORD=changeme
+DEFAULT_EMAIL=admin@example.com
+```
+
+**Why these variables?**
+- Many services (Nextcloud, Grafana, databases, etc.) use similar admin credentials
+- Setting defaults here makes it easier to manage and remember passwords
+- You can change these to your preferred values
+- Individual services will use these defaults unless overridden
+
+### 4. Timezone
+
+Set your timezone. Common options:
+- `America/New_York`
+- `America/Los_Angeles`
+- `Europe/London`
+- `Asia/Tokyo`
+- `Australia/Sydney`
+
+### 4. Authelia Secrets
+
+**⚠️ IMPORTANT:** These are auto-generated by the setup script. Do NOT set them manually.
+
+The `setup-homelab.sh` script will generate secure random secrets for:
+- JWT Secret (64 hex characters)
+- Session Secret (64 hex characters)
+- Storage Encryption Key (64 hex characters)
+
+### 5. VPN Configuration (Optional)
+
+If you want to route download services through VPN:
+
+1. Get Surfshark WireGuard credentials
+2. Extract the private key from your `.conf` file
+3. Add to `.env`:
+
+```bash
+SURFSHARK_PRIVATE_KEY=your-private-key-here
+```
+
+## Setup Process
+
+### Step 1: Copy the Template
+
+```bash
+# Copy the example file (this creates your .env file)
+cp .env.example .env
+```
+
+### Step 2: Edit Required Variables
+
+Open `.env` in your editor and update these essential variables:
+
+```bash
+# Required: Set your domain
+DOMAIN=yourdomain.duckdns.org
+DUCKDNS_TOKEN=your-actual-duckdns-token
+DUCKDNS_SUBDOMAINS=yourdomain
+
+# User Configuration (Linux user IDs)
+PUID=1000
+PGID=1000
+
+# Required: Set default credentials
+DEFAULT_USER=admin
+DEFAULT_PASSWORD=your-secure-password
+DEFAULT_EMAIL=your-email@example.com
+
+# Required: Set your timezone
+TZ=America/New_York
+
+# Optional: Configure VPN if using download services
+# Note: these are not the same as what you use to log into surfshark.com with
+SURFSHARK_USERNAME=your-surfshark-username
+SURFSHARK_PASSWORD=your-surfshark-password
+```
+
+### Step 3: Review and Customize
+
+The `.env.example` file contains all available configuration options. Review and customize:
+
+- **Default Credentials**: Used by multiple services for consistency
+- **Service-Specific Settings**: API keys, database passwords, etc.
+- **Directory Paths**: Adjust for your storage setup
+- **Optional Features**: VPN, monitoring, development tools
+
+## Validation
+
+After creating your `.env` file:
+
+```bash
+# Check that all required variables are set
+grep -E "^(DOMAIN|DUCKDNS_TOKEN|PUID|PGID|TZ|DEFAULT_USER|DEFAULT_PASSWORD|DEFAULT_EMAIL)=" .env
+
+# Validate domain format
+echo $DOMAIN | grep -E "\.duckdns\.org$"
+```
+
+## Security Notes
+
+- Never commit `.env` files to git
+- Keep your DuckDNS token secure
+- The setup script generates cryptographically secure secrets for Authelia
+- VPN keys should be kept confidential
+
+## Troubleshooting
+
+**Missing .env file:**
+```
+Error: .env file not found
+```
+→ Copy the example file: `cp .env.example .env`
+
+**Invalid domain:**
+```
+Error: DOMAIN must end with .duckdns.org
+```
+→ Check your domain format in the `.env` file
+
+**Missing DuckDNS token:**
+```
+Error: DUCKDNS_TOKEN is required
+```
+→ Get your token from duckdns.org and add it to `.env`
+
+**Permission issues:**
+```
+Error: Cannot write to .env
+```
+→ Check file permissions: `chmod 600 .env`

docs/getting-started.md

@@ -4,7 +4,8 @@ Welcome to your AI-powered homelab! This guide will walk you through setting up
 
 ## Getting Started Checklist
 - [ ] Clone this repository to your home folder
-- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](#prerequisites))
+- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](env-configuration.md))
+- [ ] Forward ports 80 and 443 from your router to your server
 - [ ] Run setup script (generates Authelia secrets and admin user) ([setup-homelab.sh](../scripts/setup-homelab.sh))
 - [ ] Log out and back in for Docker group permissions
 - [ ] Run deployment script (deploys all core, infrastructure & dashboard services) ([deploy-homelab.sh](../scripts/deploy-homelab.sh))

docs/post-setup.md

@@ -4,7 +4,7 @@ Congratulations! Your AI-powered homelab is now running. Here's what to do next.
 
 ## Access Your Services
 
-- **Homepage**: `https://home.yourdomain.duckdns.org`
+- **Homepage**: `https://homepage.yourdomain.duckdns.org`
   - Great place to start exploring your services
   - After configuring your services, come back and add widgets with API keys (optional)
   - Or ask the AI to find the API keys and add the widgets
@@ -60,6 +60,46 @@ docker compose down -v --remove-orphans
 docker system prune -a --volumes
 ```
 
+## Set Up Backups
+
+Your homelab includes comprehensive backup solutions. The default setup includes Backrest (Restic-based) for automated backups.
+
+### Quick Backup Setup
+
+1. **Access Backrest**: `https://backrest.yourdomain.duckdns.org`
+2. **Configure repositories**: Add local or cloud storage destinations
+3. **Set up schedules**: Configure automatic backup schedules
+4. **Add backup jobs**: Create jobs for your important data
+
+### What to Back Up
+
+- **Configuration files**: `/opt/stacks/*/config/` directories
+- **Databases**: Service-specific database volumes
+- **User data**: Nextcloud files, Git repositories, etc.
+- **Media libraries**: Movies, TV shows, music (if space allows)
+
+### Backup Commands
+
+```bash
+# Manual backup of a volume
+docker run --rm \
+  -v source-volume:/data \
+  -v /mnt/backups:/backup \
+  busybox tar czf /backup/volume-backup-$(date +%Y%m%d).tar.gz /data
+
+# List Backrest configurations
+cd /opt/stacks/utilities/backrest
+docker compose exec backrest restic snapshots
+
+# Restore from backup
+docker run --rm \
+  -v target-volume:/data \
+  -v /mnt/backups:/backup \
+  busybox tar xzf /backup/volume-backup.tar.gz -C /
+```
+
+For detailed backup configuration, see the [Restic-BackRest-Backup-Guide.md](Restic-BackRest-Backup-Guide.md).
+
 ## Troubleshooting
 
 ### Script Issues

tasks.txt

@@ -0,0 +1,14 @@
+Tasks
+
+.env.example
+    ✅ create new variables
+        DAFAULT_USER: admin
+        DEFAULT_PASSWORD: changeme
+        DEFAULT_EMAIL: admin@example.com
+
+    ✅ modify existing variables to use these 3 new variables like 
+    NEXTCLOUD_ADMIN_USER=${DEFAULT_USER}
+    except for QBITTORRENT_USER=admin should stay as is
+    the goal is ease of setup for the user
+
+✅ Then update env-configuration.md