Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

7.1 KB
Raw Blame

Contributing to Homelable

Thanks for taking the time to contribute! This document covers everything you need to get started.


Table of Contents


Ways to Contribute

  • Report bugs or unexpected behavior
  • Suggest new features or improvements
  • Fix open issues (check the issue tracker)
  • Improve documentation
  • Add service signatures to service_signatures.json

Reporting Bugs

Before opening an issue, search existing ones to avoid duplicates.

When filing a bug, include:

  • Homelable version (visible in the sidebar bottom-left)
  • Deployment method (Docker Compose, Proxmox LXC, source)
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant logs (docker compose logs backend / docker compose logs frontend)
  • Browser console errors if it's a UI issue

Suggesting Features

Open an issue with the enhancement label. Describe:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternatives you considered

For large changes, discuss first before writing code — it avoids wasted effort.


Development Setup

Prerequisites

  • Node.js 20+ and npm
  • Python 3.11–3.13 (3.14 not yet supported by all dependencies)
  • nmap installed on your system (required for scanner)
  • Docker + Docker Compose (optional, for full-stack testing)

1. Clone the repo

git clone https://github.com/Pouzor/homelable.git
cd homelable

2. Backend

cd backend
python3.13 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env             # edit AUTH_PASSWORD_HASH, SECRET_KEY, etc.

# Start the backend (auto-reloads on change)
uvicorn app.main:app --reload --port 8000

API docs available at http://localhost:8000/docs.

3. Frontend

cd frontend
npm install
npm run dev                      # http://localhost:5173

Vite proxies /api to localhost:8000 — the backend must be running.

4. Verify tooling

./scripts/verify-tooling.sh

Project Structure

homelable/
├── frontend/src/
│   ├── components/
│   │   ├── canvas/          # React Flow canvas, custom nodes & edges
│   │   ├── panels/          # Sidebar, detail panel, toolbar
│   │   ├── modals/          # Add/edit node, scan config, pending devices
│   │   └── ui/              # Shadcn/ui base components
│   ├── stores/              # Zustand state (canvas, auth, scan)
│   ├── hooks/               # Custom React hooks
│   ├── types/               # TypeScript interfaces & enums
│   ├── api/                 # Axios client & typed endpoints
│   └── utils/               # Layout, export, color helpers
│
├── backend/app/
│   ├── api/routes/          # FastAPI route handlers
│   ├── services/            # Scanner, status checker, canvas service
│   ├── db/                  # SQLAlchemy models, Alembic migrations
│   ├── schemas/             # Pydantic request/response schemas
│   └── core/                # Config, JWT, scheduler
│
├── docker/                  # Nginx configs
├── scripts/                 # LXC bootstrap, dev helpers
└── mcp/                     # MCP server (AI integration)

Coding Standards

General

  • No untested code merged — every feature or fix must include tests
  • Keep changes focused — one concern per PR

Frontend (TypeScript + React)

  • Strict TypeScript — no any, no type assertions unless truly necessary
  • React Flow node domain fields go in node.data, never on the node root
  • State management via Zustand stores — no prop drilling beyond 2 levels
  • Styling via TailwindCSS utility classes — follow the existing design system
  • Run before committing:
    cd frontend
    npm run lint
    npm run typecheck
    npm test
    

Backend (Python + FastAPI)

  • Python 3.11+ syntax
  • Pydantic v2 schemas for all request/response types
  • SQLAlchemy async sessions — never block the event loop
  • Scanner logic runs in a background thread — never in an async route directly
  • All schema changes via Alembic migrations — never modify tables directly
  • Run before committing:
    cd backend
    source .venv/bin/activate
    ruff check .
    pytest
    

Design System

Token Value
Background #0d1117
Surface #161b22
Card #21262d
Accent cyan #00d4ff
Online #39d353
Offline #f85149
Pending #e3b341
Font (UI) Inter
Font (IPs/ports) JetBrains Mono

Testing

Tests run automatically via a pre-commit hook when frontend or backend files are staged.

Frontend

cd frontend
npm test                  # run all tests
npm run test:coverage     # with coverage report

Test files live in __tests__/ next to their module, named *.test.ts(x).

What to test: Zustand store actions, utility functions, non-trivial component logic.

Backend

cd backend
source .venv/bin/activate
pytest                    # run all tests
pytest -v tests/test_nodes.py   # single file

Test files live in backend/tests/test_*.py.

What to test: all API routes (happy path + error cases), auth flows, service logic.

Use the client and headers fixtures from conftest.py — they provide an in-memory SQLite database so tests are isolated and fast.


Submitting a Pull Request

  1. Fork the repo and create a branch from main:

    git checkout -b feat/my-feature
    
  2. Make your changes — include tests.

  3. Run the full test suite (frontend + backend) and make sure everything passes.

  4. Open a PR against main:

    • Use a clear title (see commit format below)
    • Describe what changed and why
    • Reference any related issues (Closes #123)
    • Include screenshots for UI changes
  5. Keep the PR focused — one feature or fix per PR. Large refactors should be discussed in an issue first.


Commit Message Format

Follow Conventional Commits:

<type>: <short description>

[optional body]
Type When to use
feat New feature
fix Bug fix
docs Documentation only
refactor Code change with no behavior change
test Adding or fixing tests
chore Build, deps, tooling

Examples:

feat: add logout button to sidebar
fix: stop click propagation on pending device checkbox
docs: add CONTRIBUTING.md

Questions?

Open a GitHub Discussion or drop a comment on a relevant issue.