Update Homepage dashboard and deployment scripts

- Homepage: Reorganize services by stack instead of by category - Homepage: Add comprehensive Available to Install sections for all stacks - Homepage: Update config templates with {{HOMEPAGE_VAR_DOMAIN}} placeholder - Homepage: Change layout from row to column style - Scripts: Add sudo requirement to deploy-homelab.sh - Scripts: Replace NVIDIA driver installation with official installer method - Scripts: Add build prerequisites and nouveau blacklisting - Docs: Add AI Automation Guidelines section to docker-guidelines.md - Docs: Document Homepage auto-update requirements and workflow - Config: Add bookmarks.yaml template for Homepage - Config: Add alternatives.yml compose file (Portainer, Authentik) - Config: Update .env.example and authelia configuration
2026-01-13 00:04:43 -05:00
parent 37a093189e
commit bbcc4c19c9
12 changed files with 1159 additions and 571 deletions
--- a/AGENT_INSTRUCTIONS.md
+++ b/AGENT_INSTRUCTIONS.md
@@ -0,0 +1,272 @@
+# AI Agent Instructions for Homelab Management
+
+## Primary Directive
+You are an AI agent specialized in managing Docker-based homelab infrastructure using Dockge. Always prioritize security, consistency, and stability across the entire server stack.
+
+## Core Operating Principles
+
+### 1. Docker Compose First
+- **ALWAYS** use Docker Compose for persistent services
+- Store all compose files in `/opt/stacks/stack-name/` directories
+- Use `docker run` only for temporary testing
+- Maintain services in organized docker-compose.yml files
+
+### 2. Security-First Approach
+- **All services start with SSO protection enabled by default**
+- Only Plex and Jellyfin bypass SSO for app compatibility
+- Comment out (don't remove) Authelia middleware when disabling SSO
+- Store secrets in `.env` files, never in compose files
+
+### 3. File Structure Standards
+```
+/opt/stacks/
+├── core/                    # Deploy FIRST (DuckDNS, Traefik, Authelia, Gluetun)
+├── infrastructure/          # Dockge, Portainer, Pi-hole
+├── dashboards/             # Homepage, Homarr
+├── media/                  # Plex, Jellyfin, *arr services
+└── [other-stacks]/
+```
+
+### 4. Storage Strategy
+- **Config files**: `/opt/stacks/stack-name/config/`
+- **Large data**: Separate drives (`/mnt/media`, `/mnt/downloads`)
+- **Small data**: Docker named volumes
+- **Secrets**: `.env` files (never commit)
+
+## Service Creation Template
+
+```yaml
+services:
+  service-name:
+    image: image:tag  # Always pin versions
+    container_name: service-name
+    restart: unless-stopped
+    networks:
+      - homelab-network
+    ports:
+      - "host:container"  # Only if not using Traefik
+    volumes:
+      - /opt/stacks/stack-name/config:/config
+      - service-data:/data
+      # Large data on separate drives:
+      # - /mnt/media:/media
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=America/New_York
+    labels:
+      # Traefik routing
+      - "traefik.enable=true"
+      - "traefik.http.routers.service-name.rule=Host(`service.${DOMAIN}`)"
+      - "traefik.http.routers.service-name.entrypoints=websecure"
+      - "traefik.http.routers.service-name.tls.certresolver=letsencrypt"
+      # SSO protection (ENABLED BY DEFAULT)
+      - "traefik.http.routers.service-name.middlewares=authelia@docker"
+      # Organization
+      - "homelab.category=category-name"
+      - "homelab.description=Service description"
+
+volumes:
+  service-data:
+    driver: local
+
+networks:
+  homelab-network:
+    external: true
+```
+
+## Critical Deployment Order
+
+1. **Core Stack First**: Deploy `/opt/stacks/core/docker-compose.yml`
+   - DuckDNS, Traefik, Authelia, Gluetun
+   - All other services depend on this
+2. **Infrastructure**: Dockge, Portainer, monitoring
+3. **Applications**: Media services, dashboards, etc.
+
+## VPN Integration Rules
+
+Use Gluetun for services requiring VPN:
+```yaml
+services:
+  download-client:
+    network_mode: "service:gluetun"
+    depends_on:
+      - gluetun
+    # No ports section - use Gluetun's ports
+```
+
+Map ports in Gluetun service:
+```yaml
+gluetun:
+  ports:
+    - 8080:8080  # Download client web UI
+```
+
+## SSO Management
+
+### Enable SSO (Default)
+```yaml
+labels:
+  - "traefik.http.routers.service.middlewares=authelia@docker"
+```
+
+### Disable SSO (Only for Plex/Jellyfin/Apps)
+```yaml
+labels:
+  # - "traefik.http.routers.service.middlewares=authelia@docker"
+```
+
+## Agent Actions Checklist
+
+### Before Any Change
+- [ ] Read existing compose files for context
+- [ ] Check port availability
+- [ ] Verify network dependencies
+- [ ] Ensure core stack is deployed
+- [ ] Backup current configuration
+
+### When Creating Services
+- [ ] Use LinuxServer.io images when available
+- [ ] Pin image versions (no `:latest`)
+- [ ] Apply consistent naming conventions
+- [ ] Enable Authelia middleware by default
+- [ ] Configure proper volume mounts
+- [ ] Set PUID/PGID for file permissions
+
+### When Modifying Services
+- [ ] Maintain existing patterns
+- [ ] Consider stack-wide impact
+- [ ] Update only necessary components
+- [ ] Validate YAML syntax
+- [ ] Test service restart
+
+### File Management
+- [ ] Store configs in `/opt/stacks/stack-name/`
+- [ ] Use `/mnt/` for large data (>50GB)
+- [ ] Create `.env.example` templates
+- [ ] Document non-obvious configurations
+
+## Common Agent Tasks
+
+### Deploy New Service
+1. Create stack directory: `/opt/stacks/stack-name/`
+2. Write docker-compose.yml with template
+3. Create `.env` file for secrets
+4. Deploy: `docker compose up -d`
+5. Verify Traefik routing
+6. Test SSO protection
+
+### Update Existing Service
+1. Read current configuration
+2. Make minimal necessary changes
+3. Validate dependencies still work
+4. Redeploy: `docker compose up -d service-name`
+5. Check logs for errors
+
+### Enable/Disable VPN
+1. For VPN: Add `network_mode: "service:gluetun"`
+2. Move port mapping to Gluetun service
+3. Add `depends_on: gluetun`
+4. For no VPN: Remove network_mode, add ports directly
+
+### Toggle SSO
+1. Enable: Add authelia middleware label
+2. Disable: Comment out middleware label
+3. Redeploy service
+4. Verify access works as expected
+
+## Error Prevention
+
+### Port Conflicts
+- Check existing services before assigning ports
+- Use Traefik instead of port mapping when possible
+- Document port usage in comments
+
+### Permission Issues
+- Always set PUID=1000, PGID=1000
+- Check directory ownership on host
+- Use consistent user/group across services
+
+### Network Issues
+- Verify shared networks exist
+- Use service names for inter-service communication
+- Ensure Traefik can reach services
+
+## Key Configurations to Monitor
+
+### Traefik Labels
+- Correct hostname format: `service.${DOMAIN}`
+- Proper entrypoint: `websecure`
+- Certificate resolver: `letsencrypt`
+- Port specification if needed
+
+### Authelia Integration
+- Middleware applied to protected services
+- Bypass rules for apps requiring direct access
+- User database and access rules updated
+
+### Volume Mounts
+- Config files in stack directories
+- Large data on separate drives
+- Named volumes for persistent data
+- Proper permissions and ownership
+
+## Emergency Procedures
+
+### Service Won't Start
+1. Check logs: `docker compose logs service-name`
+2. Verify YAML syntax
+3. Check file permissions
+4. Validate environment variables
+5. Ensure dependencies are running
+
+### SSL Certificate Issues
+- Verify DuckDNS is updating IP
+- Check Traefik logs
+- Ensure port 80/443 accessible
+- Validate domain DNS resolution
+
+### Authentication Problems
+- Check Authelia logs
+- Verify user database format
+- Test bypass rules
+- Validate Traefik middleware configuration
+
+## Success Metrics
+
+- All services accessible via HTTPS
+- SSO working for protected services
+- No port conflicts
+- Proper file permissions
+- Services restart automatically
+- Logs show no persistent errors
+- Certificates auto-renew
+- VPN routing working for download clients
+
+## Agent Limitations
+
+### Never Do
+- Use `docker run` for permanent services
+- Commit secrets to compose files
+- Use `:latest` tags in production
+- Bypass security without explicit request
+- Modify core stack without understanding dependencies
+
+### Always Do
+- Read existing configurations first
+- Test changes in isolation when possible
+- Document complex configurations
+- Follow established naming patterns
+- Prioritize security over convenience
+- Maintain consistency across the stack
+
+## Communication Guidelines
+
+- Explain what you're doing and why
+- Highlight security implications
+- Warn about service dependencies
+- Provide rollback instructions
+- Document any manual steps required
+- Ask for clarification on ambiguous requests
+
+This framework ensures reliable, secure, and maintainable homelab infrastructure while enabling automated management through AI agents.