homelab hub - Moses Yebei

The Problem

Home labs accumulate scattered infrastructure — VMs on one hypervisor, apps on another, storage and shares in separate tools, network topology in a spreadsheet. Tracking relationships between these entities (which VM runs which app, which storage hosts which share) becomes manual and error-prone. This repo is a self-hosted single-pane-of-glass for that inventory, with a network map to visualize how things connect.

What This Does

homelab-hub is a Flask + Svelte web app that stores your homelab inventory in SQLite and exposes it through a browser UI. The backend (backend/app/) defines SQLAlchemy models for hardware, vm, app_service, storage, share, network, misc, and document, each with full CRUD. The frontend (frontend/src/pages/) provides three views: InventoryPage.svelte for tabular CRUD, MapPage.svelte for a Cytoscape.js graph of relationships, and DocsPage.svelte for markdown documentation with live preview.

This is a fork of RaidOwl/homelab-hub (698 stars upstream), with 0 stars and no description of what changed. The README is upstream's, including Docker commands pointing at the raidowl/homelab-hub image — not this fork's own build.

How It Is Wired

Execution starts at frontend/index.html, which loads frontend/src/main.js and mounts App.svelte. That routes to the three page components, which call frontend/src/lib/api.js for all HTTP requests. On the backend, backend/wsgi.py boots the Flask app in backend/app/__init__.py; backend/docker-entrypoint.sh runs Alembic migrations on container start, then launches Gunicorn.

The critical hub is backend/app/routes/_crud_factory.py. It generates the list/detail/create/update/delete handlers for every entity type, and all ten route modules (apps.py, hardware.py, vms.py, storage.py, networks.py, shares.py, misc.py, documents.py, inventory.py, map_routes.py) funnel through it. backend/app/models/base.py is the declarative base every model inherits. The blast radius is concentrated: a change to _crud_factory.py or base.py affects all entity types at once. That's a cost if you need to diverge behavior per entity — the factory is the single point of variation. Nine Alembic migrations (backend/migrations/versions/) evolve the SQLite schema; migration_helpers.py supports them.

The map feature is the only path that doesn't purely use the factory: map_routes.py builds the graph from all entity types and their relationships, served to NetworkMap.svelte.

How To Use It

The README documents Docker deployment, but those commands pull the upstream raidowl/homelab-hub image. For this fork, build from the local Dockerfile:

docker build -t homelab-hub .
docker run -d --name homelab-hub -p 8000:8000 -v ./data:/data homelab-hub

Data persists in ./data/. For local development: pip install -r backend/requirements.txt (Python 3.14+), then npm install in frontend/ and npm run dev (Vite). The backend serves on port 8000; the Vite dev server proxies API calls. No environment variables are documented in the repo.

Real-World Use

A homelab operator with a Proxmox host, a NAS, and a few Docker apps imports each into the inventory, links the VM to its hypervisor and the shares to their storage device, then uses the map view to see the topology before touching anything. The JSON export/import in inventory.py gives a backup path before hardware changes.

Code Health & Issues

Static analysis found no test files repository-wide and no CI/CD pipeline (no .github/ config). Both are Medium severity SDLC gaps: untested code paths and no automated build gate. Additional observations from the file structure: the README's Docker instructions point at the upstream image, not this fork, which will confuse anyone who clones this repo expecting those commands to work. The schema is actively evolving (nine migrations), so expect churn in the models and factory.

The Bottom Line

A well-structured CRUD app with a genuinely useful network visualization, and the factory pattern keeps per-entity routes small. The lack of tests and CI is the main risk for anyone modifying it, and the fork's README/image mismatch needs resolving. Suitable for a homelab operator who wants a unified inventory, not for production-critical use without adding test coverage.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

82 files

Python38
Svelte24
JavaScript5
JSON3
Markdown1
Shell1

ReactSvelteDjangoDocker

Module dependencies

The 10 most depended-upon modules of 33, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_backend_app_models___init__["__init__"] n1_backend_app_models_base["base"] n2_end_app_routes__crud_factory["_crud_factory"] n3_backend_app_routes___init__["__init__"] n4_backend_app_routes_apps["apps"] n5_backend_app_routes_hardware["hardware"] n6_backend_app_routes_inventory["inventory"] n7_backend_app_routes_misc["misc"] n8_backend_app_routes_networks["networks"] n9_backend_app_routes_shares["shares"] n0_backend_app_models___init__ --> n1_backend_app_models_base n3_backend_app_routes___init__ --> n5_backend_app_routes_hardware n3_backend_app_routes___init__ --> n4_backend_app_routes_apps n3_backend_app_routes___init__ --> n9_backend_app_routes_shares n3_backend_app_routes___init__ --> n8_backend_app_routes_networks n3_backend_app_routes___init__ --> n7_backend_app_routes_misc n3_backend_app_routes___init__ --> n6_backend_app_routes_inventory n2_end_app_routes__crud_factory --> n0_backend_app_models___init__ n4_backend_app_routes_apps --> n0_backend_app_models___init__ n4_backend_app_routes_apps --> n2_end_app_routes__crud_factory n5_backend_app_routes_hardware --> n0_backend_app_models___init__ n5_backend_app_routes_hardware --> n2_end_app_routes__crud_factory n6_backend_app_routes_inventory --> n0_backend_app_models___init__ n6_backend_app_routes_inventory --> n1_backend_app_models_base n7_backend_app_routes_misc --> n0_backend_app_models___init__ n7_backend_app_routes_misc --> n2_end_app_routes__crud_factory n8_backend_app_routes_networks --> n0_backend_app_models___init__ n8_backend_app_routes_networks --> n2_end_app_routes__crud_factory

Dependencies

7 of 15 declared dependencies are a major version behind. Resolved 15 of 15 against the registry.

Package	Declared	Latest	Behind
`@sveltejs/vite-plugin-svelte`	^3.1.0	7.3.0	4 major
`gunicorn`	==23.0.0	26.0.0	3 major
`vite`	^5.4.0	8.2.1	3 major
`cytoscape-dagre`	^2.5.0	4.0.0	2 major
`flask-cors`	==5.0.1	6.0.5	1 major
`svelte-spa-router`	^4.0.1	5.1.1	1 major
`svelte`	^4.2.19	5.56.9	1 major

Findings

MediumNo test files detected - untested code paths repository-wide
MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high5

medium3

low1

Upgrade the pinned dependency carrying a published advisoryhigh8 occurrences

flask-cors@5.0.1 CVE-2024-6866 (high) +5 more; flask@3.0.3 CVE-2026-27205 (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Add a test suite; this repository has nonehigh66 occurrences

66 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Add a workflow that builds and tests this repositoryhigh

43 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh2 occurrences

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Turn off debug mode and drive it from the environmenthigh

backend/wsgi.py

app.run(debug=True)

Django and Flask debug pages render local variables, settings and the full traceback to whoever triggered the error, so one unhandled exception publishes the database password to a stranger, and Werkzeug's debugger additionally offers a remote shell.

Fix: Read it from the environment with a safe default: DEBUG = os.environ.get("DEBUG") == "1".

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:24-alpine, python:3.14-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.