Skip to content

Commit 3cb0b73

Browse files
riccjohnriccjohn
committed
Update README
1 parent 1b68329 commit 3cb0b73

File tree

1 file changed

+125
-45
lines changed

1 file changed

+125
-45
lines changed

‎README.md‎

Lines changed: 125 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,165 @@
11
# Home Network Server
22

3-
A self-hosted home network server setup running on Ubuntu Server, managed entirely through Docker Compose.
3+
[![Docker](https://img.shields.io/badge/Docker-Required-2496ED?logo=docker)](https://www.docker.com/)
4+
[![Docker Compose](https://img.shields.io/badge/Docker%20Compose-Required-2496ED?logo=docker)](https://docs.docker.com/compose/)
5+
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-339933?logo=node.js)](https://nodejs.org/)
6+
[![pnpm](https://img.shields.io/badge/pnpm-8.15.4-F69220?logo=pnpm)](https://pnpm.io/)
7+
[![License](https://img.shields.io/badge/License-Unlicense-lightgrey)](LICENSE)
8+
9+
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.
410

511
## Overview
612

713
This project provides a complete home network infrastructure including:
814

915
- **Pi-hole** - Network-wide DNS and ad-blocking
1016
- **Homepage** - Service dashboard and navigation hub
11-
- **Traefik** - Reverse proxy for easy service access
12-
- **Additional Services** - Jellyfin, Syncthing, and more
17+
- **Traefik** - Reverse proxy for easy service access (planned)
18+
- **Tailscale** - Secure remote access VPN (planned)
19+
- **Additional Services** - Jellyfin, Syncthing, Code-Server, and more (planned)
1320

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

16-
## Planning
23+
## Services
1724

18-
See [PLANNING.md](./PLANNING.md) for the complete implementation plan, including:
25+
### Currently Implemented
1926

20-
- Phased rollout strategy
21-
- Architecture overview
22-
- Security considerations
23-
- CI/CD practices
24-
- Network configuration details
27+
- **Pi-hole** - Network-wide DNS and ad-blocking service
28+
- **Homepage** - Service dashboard and navigation hub
2529

26-
## Quick Start
30+
### Planned Services
2731

28-
1. Clone this repository
29-
2. Run the setup script:
30-
```bash
31-
./setup.sh
32-
```
33-
3. Edit `.env` file with your settings
34-
4. Start services:
35-
```bash
36-
docker compose up -d
37-
```
32+
- **Traefik** - Reverse proxy with automatic SSL/TLS
33+
- **Tailscale** - Secure remote access VPN
34+
- **Jellyfin** - Media streaming server
35+
- **Syncthing** - File synchronization
36+
- **Code-Server** - VSCode in browser for remote development
3837

39-
## Current Status
38+
For detailed progress information and implementation status, see [PLANNING.md](./PLANNING.md).
4039

41-
✅ **Phase 1: Pi-hole MVP** - Ready for deployment
40+
## Prerequisites
4241

43-
See [PLANNING.md](./PLANNING.md) for the complete implementation roadmap.
42+
Before setting up the home network server, ensure you have the following installed:
4443

45-
## Services
44+
- **Docker** - Container runtime ([Install Docker](https://docs.docker.com/get-docker/))
45+
- **Docker Compose** - Container orchestration ([Install Docker Compose](https://docs.docker.com/compose/install/))
46+
- **Node.js** - Version 20.0.0 or higher ([Install Node.js](https://nodejs.org/))
47+
- **pnpm** - Version 8.15.4 ([Install pnpm](https://pnpm.io/installation))
4648

47-
### Pi-hole
49+
### Verify Prerequisites
4850

49-
Network-wide DNS and ad-blocking service.
51+
```bash
52+
# Check Docker
53+
docker --version
5054

51-
**Quick Setup:**
55+
# Check Docker Compose
56+
docker compose version
5257

53-
1. Run `./setup.sh` (auto-detects server IP)
54-
2. Configure router DHCP DNS to use your server IP
55-
3. Start: `docker compose up -d`
56-
4. Access: `http://YOUR_SERVER_IP/admin`
58+
# Check Node.js
59+
node --version # Should be >= 20.0.0
5760

58-
**Documentation:**
61+
# Check pnpm
62+
pnpm --version # Should be 8.15.4
63+
```
5964

60-
- [Pi-hole Setup & Configuration](./docs/pihole-setup.md)
61-
- [Pi-hole Troubleshooting](./docs/pihole-troubleshooting.md)
65+
## Installation & Setup
6266

63-
**Scripts:**
67+
### 1. Clone the Repository
6468

65-
- `scripts/pihole/test-pihole.sh` - Test Pi-hole functionality
66-
- `scripts/pihole/diagnose-pihole.sh` - Network diagnostic tool
67-
- `scripts/pihole/update-server-ip.sh` - Update server IP in .env
69+
```bash
70+
git clone <repository-url>
71+
cd home-network
72+
```
73+
74+
### 2. Install Development Dependencies
75+
76+
```bash
77+
pnpm install
78+
```
79+
80+
### 3. Run Setup Script
81+
82+
The setup script will:
83+
84+
- Verify Docker and Docker Compose are installed
85+
- Create necessary directories
86+
- Auto-detect your server IP address
87+
- Create or update the `.env` file
88+
89+
```bash
90+
./setup.sh
91+
```
92+
93+
### 4. Configure Environment Variables
94+
95+
Edit the `.env` file with your settings. See `.env.example` for all available environment variables and their descriptions.
96+
97+
### 5. Configure Router DNS
98+
99+
Configure your router to use Pi-hole as the DNS server:
100+
101+
1. Log into your router's admin interface
102+
2. Find DNS settings (usually in DHCP or Network settings)
103+
3. Set Primary DNS to your server IP (e.g., `192.168.0.243`)
104+
4. Set Secondary DNS to a backup (e.g., `8.8.8.8` or `1.1.1.1`)
105+
5. Save and restart router if needed
106+
107+
### 6. Start Services
108+
109+
```bash
110+
docker compose up -d
111+
```
112+
113+
### 7. Access Services
114+
115+
- **Pi-hole Admin**: `http://YOUR_SERVER_IP/admin`
116+
- **Homepage**: `http://YOUR_SERVER_IP:3000`
68117

69118
## Project Structure
70119

71120
```
72121
home-network/
73122
├── docker-compose.yml # Main orchestration file
74123
├── .env # Environment variables (gitignored)
75-
├── setup.sh # Initial setup script
76-
├── docs/ # Service-specific documentation
124+
├── .env.example # Environment template
125+
├── setup.sh # Initial setup script
126+
├── package.json # Node.js dependencies
127+
├── PLANNING.md # Detailed planning and progress document
128+
├── docs/ # Service-specific documentation
77129
│ └── pihole-*.md
78-
├── scripts/ # Service-specific scripts
130+
├── scripts/ # Service-specific scripts
79131
│ └── pihole/
80-
└── [service]/ # Service data directories
132+
├── pihole/ # Pi-hole data directories
133+
│ ├── etc/
134+
│ └── etc-dnsmasq.d/
135+
└── homepage/ # Homepage configuration
136+
└── config/
81137
```
82138

83-
## License
139+
## Progress & Planning
140+
141+
For detailed information about:
142+
143+
- Implementation progress and status
144+
- Phased rollout strategy
145+
- Architecture overview
146+
- Security considerations
147+
- Network configuration details
148+
- Future plans and roadmap
149+
150+
See **[PLANNING.md](./PLANNING.md)** for the complete planning document.
151+
152+
## Documentation
153+
154+
- [Pi-hole Setup & Configuration](./docs/pihole-setup.md)
155+
- [Pi-hole Troubleshooting](./docs/pihole-troubleshooting.md)
156+
157+
## Scripts
158+
159+
- `scripts/pihole/test-pihole.sh` - Test Pi-hole functionality
160+
- `scripts/pihole/diagnose-pihole.sh` - Network diagnostic tool
161+
- `scripts/pihole/update-server-ip.sh` - Update server IP in .env
162+
163+
## Contributing
84164

85-
[Add your license here]
165+
This is a personal home network setup project. Contributions and suggestions are welcome!

0 commit comments

Comments
 (0)