Home Network Server

A self-hosted home network server setup running on Ubuntu Server, managed entirely through Docker Compose. This project provides a complete home network infrastructure with DNS, ad-blocking, service dashboard, reverse proxy, and secure remote access capabilities.

Overview

This project provides a complete home network infrastructure including:

• Pi-hole - Network-wide DNS and ad-blocking
• Homepage - Service dashboard and navigation hub
• Traefik - Reverse proxy for easy service access (planned)
• Tailscale - Secure remote access VPN (planned)
• Additional Services - Jellyfin, Syncthing, Code-Server, and more (planned)

All services are accessible from devices across the network (Linux, Android, TVs, Mac, iPhone, iPad, etc.).

Services

Currently Implemented

• Pi-hole - Network-wide DNS and ad-blocking service
• Homepage - Service dashboard and navigation hub

Planned Services

• Traefik - Reverse proxy with automatic SSL/TLS
• Tailscale - Secure remote access VPN
• Jellyfin - Media streaming server
• Syncthing - File synchronization
• Code-Server - VSCode in browser for remote development

For detailed progress information and implementation status, see PLANNING.md.

Prerequisites

Before setting up the home network server, ensure you have the following installed:

• Docker - Container runtime (Install Docker)
• Docker Compose - Container orchestration (Install Docker Compose)
• Node.js - Version 20.0.0 or higher (Install Node.js)
• pnpm - Version 8.15.4 (Install pnpm)

Verify Prerequisites

# Check Docker
docker --version

# Check Docker Compose
docker compose version

# Check Node.js
node --version  # Should be >= 20.0.0

# Check pnpm
pnpm --version  # Should be 8.15.4

Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd home-network

2. Install Development Dependencies

pnpm install

3. Run Setup Script

The setup script will:

• Verify Docker and Docker Compose are installed
• Create necessary directories
• Auto-detect your server IP address
• Create or update the .env file

./setup.sh

4. Configure Environment Variables

Edit the .env file with your settings. See .env.example for all available environment variables and their descriptions.

5. Configure Router DNS

Configure your router to use Pi-hole as the DNS server:

1. Log into your router's admin interface
2. Find DNS settings (usually in DHCP or Network settings)
3. Set Primary DNS to your server IP (e.g., 192.168.0.243)
4. Set Secondary DNS to a backup (e.g., 8.8.8.8 or 1.1.1.1)
5. Save and restart router if needed

6. Start Services

docker compose up -d

7. Access Services

• Pi-hole Admin: http://YOUR_SERVER_IP/admin
• Homepage: http://YOUR_SERVER_IP:3000

Project Structure

home-network/
├── docker-compose.yml      # Main orchestration file
├── .env                    # Environment variables (gitignored)
├── .env.example           # Environment template
├── setup.sh               # Initial setup script
├── package.json           # Node.js dependencies
├── PLANNING.md            # Detailed planning and progress document
├── docs/                  # Service-specific documentation
│   └── pihole-*.md
├── scripts/               # Service-specific scripts
│   └── pihole/
├── pihole/                # Pi-hole data directories
│   ├── etc/
│   └── etc-dnsmasq.d/
└── homepage/              # Homepage configuration
    └── config/

Progress & Planning

For detailed information about:

• Implementation progress and status
• Phased rollout strategy
• Architecture overview
• Security considerations
• Network configuration details
• Future plans and roadmap

See PLANNING.md for the complete planning document.

Scripts

• scripts/pihole/test-pihole.sh - Test Pi-hole functionality

Contributing

This is a personal home network setup project. Contributions and suggestions are welcome!