Project N.O.M.A.D. — Homelab Edition

Network Operations Monitoring and Automation Dashboard

Knowledge That Never Goes Offline — Now Container-Native for Your Homelab

---

Project N.O.M.A.D. Homelab Edition is a container-native fork of Project N.O.M.A.D., optimized for NAS systems and homelab environments. It runs as a portable Docker Compose stack on Unraid, TrueNAS SCALE, and any standard Docker host.

Quick Start (Docker Compose)

# 1. Clone the repository
git clone https://github.com/DocwatZ/project-nomad-homelab-edition.git
cd project-nomad-homelab-edition

# 2. Configure environment
cp .env.example .env
sed -i "s/^APP_KEY=replaceme/APP_KEY=$(openssl rand -hex 32)/" .env
sed -i "s/^DB_PASSWORD=replaceme/DB_PASSWORD=$(openssl rand -base64 24)/" .env
sed -i "s/^MYSQL_ROOT_PASSWORD=replaceme/MYSQL_ROOT_PASSWORD=$(openssl rand -base64 24)/" .env

# 3. Create data directories
sudo mkdir -p /opt/project-nomad/{storage,redis,logs/nginx}

# 4. Start the stack
docker compose up -d

Open http://localhost:8080 to access the dashboard.

Container Architecture

Service	Image	Purpose
nomad-app	project-nomad	Web UI + API server
nomad-worker	project-nomad	Background job processing
nomad-database	mysql:8.0	Persistent data storage
nomad-cache	redis:7-alpine	Cache + job queues
nomad-nginx	nginx:alpine	Reverse proxy

All services communicate over a private Docker network (nomad-internal).

NAS Compatibility

Platform	Storage Path	Guide
Unraid	/mnt/user/appdata/project-nomad	Unraid Guide
TrueNAS SCALE	/mnt/pool/apps/project-nomad	TrueNAS Guide
Linux	/opt/project-nomad	Installation Guide

NAS Install Templates

• Unraid: Community Apps XML template
• TrueNAS SCALE: Helm chart
• Any Docker host: docker-compose.yml

Storage Layout

NOMAD_DATA_DIR/
├── storage/          # Content files (ZIM, maps, uploads) — NAS share OK
├── redis/            # Redis persistence
└── logs/
    └── nginx/        # Nginx access/error logs

The MySQL database uses a Docker named volume for optimal I/O, avoiding NFS/SMB latency.

Reverse Proxy Support

Works behind common homelab reverse proxies:

Proxy	Configuration
Nginx Proxy Manager	Setup guide
Traefik	Traefik config
Caddy	Caddyfile

Monitoring Agent

Deploy lightweight monitoring agents on homelab nodes:

docker run -d --name nomad-agent \
  -p 9100:9100 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc:/host/proc:ro \
  -e NODE_NAME=my-server \
  nomad-agent

Features: CPU/RAM/disk metrics, Docker container monitoring, Prometheus /metrics endpoint.

See the Agent Guide for details.

What's Included

Capability	Powered By	What You Get
Information Library	Kiwix	Offline Wikipedia, medical references, survival guides, ebooks
AI Assistant	Ollama + Qdrant	Built-in chat with document upload and semantic search
Education Platform	Kolibri	Khan Academy courses, progress tracking, multi-user support
Offline Maps	ProtoMaps	Downloadable regional maps with search and navigation
Data Tools	CyberChef	Encryption, encoding, hashing, and data analysis
Notes	FlatNotes	Local note-taking with markdown support
System Benchmark	Built-in	Hardware scoring, Builder Tags, and community leaderboard

Device Requirements

Minimum Specs

• 2 GHz dual-core processor
• 4 GB RAM (8 GB recommended)
• 5 GB free disk space
• Docker 20.10+ and Docker Compose v2+
• Any Linux, Unraid, or TrueNAS SCALE host

Optimal Specs

• AMD Ryzen 7 / Intel Core i7 or better
• 32 GB RAM
• NVIDIA RTX 3060+ (for AI features)
• 250 GB SSD
• Stable internet connection (for initial content downloads)

Documentation

Guide	Description
Installation Guide	Docker Compose setup
Unraid Guide	Unraid-specific installation
TrueNAS Guide	TrueNAS SCALE installation
Agent Guide	Monitoring agent setup
Architecture	System design and data flow
Monitoring	Monitoring stack and Prometheus integration

Configuration

All configuration is handled through environment variables in .env. See .env.example for all options.

Key settings:

Variable	Default	Description
APP_KEY	—	Encryption key (required)
DB_PASSWORD	—	Database password (required)
URL	http://localhost:8080	External access URL
NOMAD_DATA_DIR	/opt/project-nomad	Host storage directory
PORT	8080	Application port
LOG_LEVEL	info	Log verbosity

Updating

docker compose pull
docker compose up -d

About Internet Usage & Privacy

Project N.O.M.A.D. is designed for offline usage. An internet connection is only required during the initial installation (to download dependencies) and if you (the user) decide to download additional tools and resources at a later time. Otherwise, N.O.M.A.D. does not require an internet connection and has ZERO built-in telemetry.

Contributing

Contributions are welcome and appreciated! Please read the Contributing Guide for details.

This project uses semantic versioning. The version is managed in the root package.json and automatically updated by semantic-release.

Community & Resources

• Website: www.projectnomad.us
• Discord: Join the Community
• Benchmark Leaderboard: benchmark.projectnomad.us

License

Project N.O.M.A.D. is licensed under the Apache License 2.0.