Home Server Stack

A complete self-hosted infrastructure for home automation, AI, and network services using Docker Compose.

🚀 Services

Core Services:

• AdGuard Home - Network-wide ad blocking and DNS server
• n8n - Workflow automation platform
• WireGuard - VPN for secure remote access
• Traefik - Reverse proxy for domain-based service access

Monitoring Stack:

• Grafana - Metrics visualization and dashboards
  • System Overview - CPU, memory, disk, network metrics
  • Container Health - Docker container status and resource usage
  • Resource Utilization - Historical trends and capacity planning
• Prometheus - Metrics collection and alerting
• Alertmanager - Alert routing and management
• Node Exporter - System metrics exporter
• cAdvisor - Container metrics

See SERVICES.md for the complete catalog including planned services.

📋 Quick Start

# 1. Clone the repository
git clone <your-repo-url>
cd home-server-stack

# 2. Configure environment
cp .env.example .env
nano .env  # Update SERVER_IP, TIMEZONE, passwords

# 3. Run first-time setup (includes all services + monitoring)
make setup

Note: make setup will optionally prompt you to configure Let's Encrypt SSL certificates if your .env includes DOMAIN, ACME_EMAIL, and GANDIV5_PERSONAL_ACCESS_TOKEN. Otherwise, services use self-signed certificates (browser warnings expected).

Using the Makefile:

• make help - Show all available commands
• make setup - First time setup (all services + monitoring)
• make update - Update all services to latest versions
• make start - Start all services
• make stop - Stop all services
• make logs - View logs from all services
• See make help for complete list of commands

Access Services:

All services are accessible via domain names on your local network:

• Traefik Dashboard: https://traefik.home.local
• AdGuard Home: https://adguard.home.local (DNS admin)
• n8n: https://n8n.home.local (Workflow automation)
• Grafana: https://grafana.home.local (Monitoring)
• Prometheus: https://prometheus.home.local (Metrics)
• Alertmanager: https://alerts.home.local (Alerts)

Note: Services are accessible via domain names thanks to Traefik reverse proxy and AdGuard Home DNS. Your devices must use AdGuard Home as their DNS server (configured automatically if DHCP points to the server).

Direct IP Access: Some services remain accessible via IP:port for specific operational needs:

• AdGuard Home: http://SERVER_IP:8888 (emergency access if Traefik fails)
• Prometheus: http://SERVER_IP:9090 (metrics scraping)
• Alertmanager: http://SERVER_IP:9093 (alert management)
• See SERVICES.md for complete list

See docs/SETUP.md for detailed installation instructions.

🔒 SSL Certificates

By default, services use self-signed certificates (browser warnings expected). For trusted Let's Encrypt certificates, see docs/CONFIGURATION.md#ssl-certificate-setup for complete setup instructions using make ssl-setup.

📚 Documentation

Getting Started

• Setup Guide - Complete installation and initial setup
• Configuration Guide - Service configuration and customization
• Requirements - System requirements and resource usage

Operations

• Operations Guide - Managing services, updates, backups
• Troubleshooting - Common issues and solutions
• Monitoring Deployment - Optional monitoring stack setup

Monitoring & Alerts

• Alerts Reference - Alert definitions and response procedures
• Operations Runbook - Detailed troubleshooting for all alerts
• Known Issues - Known bugs and workarounds

Advanced

• Remote Access Setup - Port forwarding and VPN configuration
• Architecture Overview - System design and data persistence

Implementation Tickets

• Monitoring Tickets - Monitoring implementation roadmap
• Security Tickets - Security hardening roadmap (VPN-first strategy)
• Dashboard Tickets - Homepage dashboard with integrations

🔐 Security

This project implements multi-layered defense-in-depth security with four protection layers:

Security Layers

🔥 Layer 1: Network Firewall (UFW)

• Default deny incoming, SSH rate-limited
• Only WireGuard VPN (51820/UDP) and HTTP/HTTPS (80/443) exposed
• Local network and VPN clients have full access

🛡️ Layer 2: Traefik Middleware

• IP Whitelisting: Admin interfaces only accessible from local network/VPN
• Security Headers: HSTS, XSS protection, frame deny
• Rate Limiting: 10 req/min for admin, 100 req/min for webhooks

🚫 Layer 3: Fail2ban

• Auto-bans IPs after repeated auth failures (3 → 1h ban)
• Detects scanning activity (10 x 404 → 24h ban)
• Monitors webhook abuse (20 x rate limit → 10m ban)

📊 Layer 4: Prometheus Security Monitoring

• Real-time alerts for auth failures, scanning, DDoS attempts
• Tracks rate limit enforcement and server errors
• Monitors fail2ban and Traefik availability

Access Model

• Admin Interfaces (n8n, Grafana, etc.): VPN or local network only
• Future Webhooks: Public access with rate limiting (not yet configured)
• VPN Primary Boundary: WireGuard for all remote admin access

See SECURITY.md for security policy and security-tickets/README.md for the complete security roadmap.

📊 Dashboard & Automation

This stack includes a comprehensive dashboard with location tracking and integrations:

• Homepage: Unified dashboard for all services
• Home Assistant: Automation hub and location tracking
• Backend API: Custom integrations for BOM weather, Transport NSW, traffic

Deploy Dashboard Services

docker compose -f docker-compose.dashboard.yml up -d

See docs/DASHBOARD_SETUP.md for detailed instructions.

Dashboard Features

• 🌤️ Australian BOM weather for North Parramatta
• 📅 Google Calendar integration
• 🚊 Real-time Transport NSW departures
• 🚗 Traffic conditions for configurable routes
• 📍 Family location tracking via iOS/Android
• 🐳 Docker container monitoring

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on:

• Submitting bug reports and feature requests
• Development workflow and branching strategy
• Pull request process

📊 System Requirements

Minimum:

• 8 GB RAM (16 GB recommended)
• 500 GB storage (1 TB recommended)
• Linux-based OS (tested on Ubuntu Server 24.04 LTS)
• Docker and Docker Compose installed

See docs/REQUIREMENTS.md for detailed requirements.

📄 License

This project is open source. Individual services maintain their own licenses:

• AdGuard Home: GPL-3.0
• n8n: Fair-code (Sustainable Use License)
• Traefik: MIT
• Grafana: AGPL-3.0
• Prometheus: Apache-2.0

💬 Support

• Documentation: Check the docs/ directory
• Issues: GitHub Issues
• Service-specific docs:
  • AdGuard Home
  • n8n
  • Traefik

---

Project Status: Active Development Latest Update: 2025-10-16