Home Lab Tools

A collection of command-line utilities that provide visibility into a home lab's Docker + Nginx + Cloudflare stack. These tools scan docker-compose files and nginx configs, correlate services with their reverse proxy and Cloudflare tunnel routes, and generate reports and a static web explorer.

• deployment_report.py — Scans docker-compose stacks and nginx configs, correlates services with Nginx proxies and Cloudflare routes, and produces formatted reports, JSON export, and Chrome-importable bookmarks.
• cloudflare_to_csv.py — Converts the manually copy-pasted Cloudflare Published Application Routes table into a CSV file for use with deployment_report.py.
• nginx_config_manager.py — Renames nginx config files to match their server_name directive and updates symlinks in sites-enabled.

A static web UI (home-lab/) generated from the JSON export that provides an interactive view of your deployment stack.

Summary stat cards (Docker services, Nginx proxies, Cloudflare routes, exposed ports) and quick-access service cards with CF/Static badges.

Filterable, sortable table with status badges: Full Stack, Partial, Docker Only, Proxy Only, Static.

D3 force-directed visualization with three columns (Cloudflare | Nginx | Docker). Click a node to highlight its full chain; double-click to clear.

Docker host ports and Nginx listen ports mapped to service names.

• Parses docker-compose.yml files and substitutes environment variables from .env / stack.env
• Parses nginx site configs to extract proxy_pass upstreams and static root paths
• Correlates services ↔ proxies by port, proxies ↔ Cloudflare routes by hostname
• Multiple output formats: grid, simple, github, pipe, html, markdown
• Export JSON for the Home Lab Explorer web UI
• Export Chrome-importable bookmarks HTML
• Port usage summary for capacity planning

• Parses nginx sites-available configs for server_name directives
• Renames config files to match the primary server name
• Automatically updates symlinks in sites-enabled
• Dry-run mode to preview changes without modifying anything

Cloudflare doesn't offer a direct CSV export for tunnel routes, so the source data requires a manual copy-paste step:

1. Log in to the Cloudflare dashboard
2. Navigate to Zero Trust → Networks → Tunnels
3. Click your tunnel, then open the Public Hostnames tab
4. The Published application routes table is displayed — select all text in the table and copy it
5. Paste the copied text into a plain text file (e.g., published-application-routes.txt)
6. Run cloudflare_to_csv.py to convert it to CSV

The raw copy-pasted text looks like this (6 lines per route):

Published application routes  Path  Service  Origin configurations  Menu
1
n8n.drskippy.app
*
http://192.168.1.90:5678

2
mealie.drskippy.app
*
http://192.168.1.91:9000

poetry install

The run.sh script runs the three-step pipeline:

# Step 1: Convert the copy-pasted Cloudflare routes to CSV
poetry run python ./bin/cloudflare_to_csv.py \
  ./test_samples/cloudflare/published-application-routes.txt \
  ./test_samples/cloudflare/published-application-routes.csv

# Step 2: Generate the report, bookmarks, and JSON for the web explorer
poetry run python ./bin/deployment_report.py \
  --compose-dir /opt/stacks/ \
  --nginx-dir /etc/nginx/sites-available/ \
  --cloudflare-csv test_samples/cloudflare/published-application-routes.csv \
  -b \
  --json home-lab/data/deployment.json

# Step 3: Copy the web explorer to the web server
sudo cp -r home-lab/* /var/www/html/weewx/home-lab/

All flags:

-c, --compose-dir    Path to directory containing docker-compose files (default: ./test_samples/compose)
-n, --nginx-dir      Path to nginx sites-available directory (default: ./test_samples/sites-available)
    --cloudflare-csv Path to Cloudflare routes CSV file (optional)
-f, --format         Output format: grid, simple, github, pipe, html, markdown (default: grid)
-s, --summary        Show port usage summary
-b, --bookmarks      Export Chrome-importable bookmarks to bookmarks.html (optionally specify path)
    --json PATH      Export deployment JSON for the Home Lab Explorer

Examples:

# Basic (uses test_samples/ defaults)
poetry run python bin/deployment_report.py

# Custom directories
poetry run python bin/deployment_report.py \
  -c /opt/stacks \
  -n /etc/nginx/sites-available

# With Cloudflare routes
poetry run python bin/deployment_report.py \
  --cloudflare-csv cloudflare-routes.csv

# Export JSON for web explorer
poetry run python bin/deployment_report.py \
  --json home-lab/data/deployment.json

# Export bookmarks
poetry run python bin/deployment_report.py -b
poetry run python bin/deployment_report.py -b /path/to/bookmarks.html

# Show port summary
poetry run python bin/deployment_report.py -s

# Markdown format for piping or saving
poetry run python bin/deployment_report.py -f markdown

# Basic usage
poetry run python bin/nginx_config_manager.py /path/to/sites-available

# Dry run (preview only)
poetry run python bin/nginx_config_manager.py /path/to/sites-available --dry-run

# With sites-enabled and log file
poetry run python bin/nginx_config_manager.py /path/to/sites-available \
  --sites-enabled /path/to/sites-enabled \
  --log-file /path/to/nginx_manager.log

Note: This tool requires a manual copy-paste step from the Cloudflare dashboard — see the Cloudflare to CSV section under Features for instructions.

# Output CSV to same directory as input
poetry run python bin/cloudflare_to_csv.py path/to/published-application-routes.txt

# Explicit output path
poetry run python bin/cloudflare_to_csv.py path/to/input.txt path/to/output.csv

.
├── bin/
│   ├── deployment_report.py
│   ├── nginx_config_manager.py
│   └── cloudflare_to_csv.py
├── home-lab/                  # Static web explorer
│   ├── index.html
│   ├── css/app.css
│   ├── js/app.js
│   └── data/                  # Generated JSON (git-ignored)
├── img/                       # Screenshots
├── test_samples/
│   ├── compose/
│   ├── sites-available/
│   └── cloudflare/
├── run.sh                     # Full pipeline script
├── pyproject.toml
├── poetry.lock
└── README.md

MIT