Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
feat(backend): STATUS_CHECKER_ENABLED switch to disable status/service checks
Tom Vaisbortba0ebd816522
diff --git a/.env.example b/.env.exampleindex da5b10c..4740b63 100644--- a/.env.example+++ b/.env.example@@ -54,6 +54,10 @@ SCANNER_HTTP_VERIFY_TLS=false# Status checker interval in secondsSTATUS_CHECKER_INTERVAL=60+# Set to false when another system owns monitoring: no status/service check+# jobs run and approvals stop defaulting devices to ping. Env-only.+# STATUS_CHECKER_ENABLED=true+# MCP server — used by the mcp service (port 8001)# MCP_API_KEY: authenticates AI clients (Claude Code, etc.) → MCP server# MCP_SERVICE_KEY: authenticates MCP server → backend (never exposed externally)diff --git a/backend/app/api/routes/scan.py b/backend/app/api/routes/scan.pyindex 812772f..30a4c8b 100644--- a/backend/app/api/routes/scan.py+++ b/backend/app/api/routes/scan.py@@ -772,7 +772,10 @@ async def bulk_approve_devices(elif not device.check_method:# Default to ping so the status checker actually polls it. Without# this the scheduler skips it (check_method NULL -> no check).- device.check_method = "ping" if device.ip else None+ # With the checker switched off there is nothing to poll for: keep+ # it NULL rather than store a probe that would start the moment the+ # switch is flipped back.+ device.check_method = "ping" if device.ip and settings.status_checker_enabled else Nonenode = Node(label=device.label,type=device.type,@@ -956,7 +959,7 @@ async def approve_device(device.status_live = "online"else:device.check_method = node_data.check_method or device.check_method or (- "ping" if device.ip else None+ "ping" if device.ip and settings.status_checker_enabled else None)device.check_target = node_data.check_target or device.check_targetif node_data.status:diff --git a/backend/app/core/config.py b/backend/app/core/config.pyindex 8d43ac1..d6400e8 100644--- a/backend/app/core/config.py+++ b/backend/app/core/config.py@@ -179,6 +179,13 @@ class Settings(BaseSettings):# Status checkerstatus_checker_interval: int = 60+ # Master switch for node and service status checks. False = the checker+ # jobs are never registered and approvals stop defaulting a device to+ # `ping`, so the backend sends no reachability probes at all (for installs+ # where another system owns monitoring). Env-only (STATUS_CHECKER_ENABLED):+ # deliberately not in load_overrides/save_overrides, so the UI cannot+ # switch it back on through scan_config.json.+ status_checker_enabled: bool = True# Per-service status checker (independent of node checks). Off by default.service_check_enabled: bool = Falsediff --git a/backend/app/core/scheduler.py b/backend/app/core/scheduler.pyindex 68969b5..c47bed0 100644--- a/backend/app/core/scheduler.py+++ b/backend/app/core/scheduler.py@@ -86,6 +86,8 @@ async def _run_status_checks() -> None:monitoring the host. `hide` (or clearing the check method) is what ends thechecks; the broadcast simply carries an empty `node_ids`."""+ if not settings.status_checker_enabled:+ returnasync with AsyncSessionLocal() as db:devices = (await db.execute(@@ -127,7 +129,7 @@ async def _run_service_checks() -> None:Device-scoped for the same reason as the status check: the services belongto the device, so one pass serves every canvas showing it."""- if not settings.service_check_enabled:+ if not (settings.status_checker_enabled and settings.service_check_enabled):returnfrom app.api.routes.status import broadcast_service_status # avoid circular import@@ -331,16 +333,17 @@ def start_scheduler() -> None:except Exception as exc:logger.warning("Failed to shut down previous scheduler instance: %s", exc)scheduler = AsyncIOScheduler()- scheduler.add_job(- _run_status_checks,- "interval",- seconds=settings.status_checker_interval,- id="status_checks",- max_instances=1,- coalesce=True,- )- if settings.service_check_enabled:- _add_service_check_job()+ if settings.status_checker_enabled:+ scheduler.add_job(+ _run_status_checks,+ "interval",+ seconds=settings.status_checker_interval,+ id="status_checks",+ max_instances=1,+ coalesce=True,+ )+ if settings.service_check_enabled:+ _add_service_check_job()if settings.proxmox_sync_enabled:_add_proxmox_sync_job()if settings.zigbee_sync_enabled:@@ -350,7 +353,10 @@ def start_scheduler() -> None:if settings.unifi_sync_enabled:_add_unifi_sync_job()scheduler.start()- logger.info("Scheduler started — status checks every %ds", settings.status_checker_interval)+ if settings.status_checker_enabled:+ logger.info("Scheduler started — status checks every %ds", settings.status_checker_interval)+ else:+ logger.info("Scheduler started — status checks disabled (STATUS_CHECKER_ENABLED=false)")def reschedule_status_checks(interval_seconds: int) -> None:@@ -360,6 +366,9 @@ def reschedule_status_checks(interval_seconds: int) -> None:if not scheduler.running:logger.warning("Scheduler not running, skipping reschedule")return+ if not scheduler.get_job("status_checks"):+ logger.info("Status checks disabled — nothing to reschedule")+ returnscheduler.reschedule_job("status_checks", trigger="interval", seconds=interval_seconds)logger.info("Status checks rescheduled to every %ds", interval_seconds)@@ -380,6 +389,9 @@ def set_service_checks_enabled(enabled: bool) -> None:"""Add or remove the service-check job on the running scheduler."""if not scheduler.running:return+ if enabled and not settings.status_checker_enabled:+ logger.info("Service checks stay off: STATUS_CHECKER_ENABLED=false")+ returnjob = scheduler.get_job("service_checks")if enabled and not job:_add_service_check_job()diff --git a/backend/tests/scan/test_scan_approve_checker_disabled.py b/backend/tests/scan/test_scan_approve_checker_disabled.pynew file mode 100644index 0000000..7a9b6a9--- /dev/null+++ b/backend/tests/scan/test_scan_approve_checker_disabled.py@@ -0,0 +1,39 @@+"""With STATUS_CHECKER_ENABLED=false an approval must not store a probe."""+import pytest+from httpx import AsyncClient+from sqlalchemy import select++from app.core.config import settings+from app.db.models import InventoryDevice, Node+++async def test_bulk_approve_leaves_check_method_null(+ client: AsyncClient, headers, two_device_inventory, db_session, monkeypatch+):+ monkeypatch.setattr(settings, "status_checker_enabled", False)+ ids = [d.id for d in two_device_inventory]+ res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)+ assert res.status_code == 200+ nodes = (await db_session.execute(select(Node))).scalars().all()+ assert nodes+ for node in nodes:+ device = await db_session.get(InventoryDevice, node.device_id)+ assert device is not None+ assert device.check_method is None+++async def test_single_approve_leaves_check_method_null(+ client: AsyncClient, headers, pending_device, db_session, monkeypatch+):+ monkeypatch.setattr(settings, "status_checker_enabled", False)+ res = await client.post(+ f"/api/v1/scan/pending/{pending_device.id}/approve",+ json={"label": "h", "type": "generic", "ip": "192.168.1.10", "status": "unknown", "services": []},+ headers=headers,+ )+ assert res.status_code == 200+ node = (await db_session.execute(select(Node))).scalars().first()+ device = await db_session.get(InventoryDevice, node.device_id)+ assert device.check_method is Nonediff --git a/backend/tests/test_status_checker_toggle.py b/backend/tests/test_status_checker_toggle.pynew file mode 100644index 0000000..b3aeed2--- /dev/null+++ b/backend/tests/test_status_checker_toggle.py@@ -0,0 +1,127 @@+"""STATUS_CHECKER_ENABLED=false: no check job is ever registered, the runners+are inert, and nothing re-enables them at runtime."""+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from app.core.scheduler import (+ _run_service_checks,+ _run_status_checks,+ reschedule_status_checks,+ set_service_checks_enabled,+ start_scheduler,+)+++def _configure(mock_settings, *, checker: bool, services: bool = False) -> None:+ mock_settings.status_checker_enabled = checker+ mock_settings.status_checker_interval = 60+ mock_settings.service_check_enabled = services+ mock_settings.service_check_interval = 300+ mock_settings.proxmox_sync_enabled = False+ mock_settings.zigbee_sync_enabled = False+ mock_settings.zwave_sync_enabled = False+ mock_settings.unifi_sync_enabled = False+++def _job_ids(mock_sched: MagicMock) -> list[str]:+ return [kw.get("id") for _, kw in mock_sched.add_job.call_args_list]+++def test_switch_defaults_to_enabled():+ from app.core.config import Settings++ assert Settings.model_fields["status_checker_enabled"].default is True+++def test_env_var_turns_the_switch_off(monkeypatch):+ from app.core.config import Settings++ monkeypatch.setenv("STATUS_CHECKER_ENABLED", "false")+ assert Settings().status_checker_enabled is False+++def test_switch_is_not_persisted_to_scan_config(tmp_path, monkeypatch):+ """The UI writes scan_config.json; it must never carry this switch."""+ from app.core.config import Settings++ monkeypatch.setenv("SQLITE_PATH", str(tmp_path / "homelab.db"))+ monkeypatch.setenv("STATUS_CHECKER_ENABLED", "false")+ s = Settings()+ (tmp_path / "scan_config.json").write_text('{"status_checker_enabled": true}')+ s.load_overrides()+ assert s.status_checker_enabled is False+++def test_start_scheduler_registers_no_check_job_when_disabled():+ mock_sched = MagicMock()+ with patch("app.core.scheduler.settings") as s, \+ patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):+ _configure(s, checker=False, services=True)+ start_scheduler()+ assert "status_checks" not in _job_ids(mock_sched)+ assert "service_checks" not in _job_ids(mock_sched)+ mock_sched.start.assert_called_once()+++def test_start_scheduler_logs_that_checks_are_disabled(caplog):+ mock_sched = MagicMock()+ with patch("app.core.scheduler.settings") as s, \+ patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched), \+ caplog.at_level("INFO", logger="app.core.scheduler"):+ _configure(s, checker=False)+ start_scheduler()+ assert "status checks disabled (STATUS_CHECKER_ENABLED=false)" in caplog.text+++def test_start_scheduler_unchanged_when_enabled():+ mock_sched = MagicMock()+ with patch("app.core.scheduler.settings") as s, \+ patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):+ _configure(s, checker=True, services=True)+ start_scheduler()+ assert "status_checks" in _job_ids(mock_sched)+ assert "service_checks" in _job_ids(mock_sched)+++async def test_run_status_checks_is_inert_when_disabled():+ with patch("app.core.scheduler.settings") as s, \+ patch("app.core.scheduler.AsyncSessionLocal") as sessions, \+ patch("app.core.scheduler.check_node", new_callable=AsyncMock) as check:+ _configure(s, checker=False)+ await _run_status_checks()+ sessions.assert_not_called()+ check.assert_not_called()+++async def test_run_service_checks_is_inert_when_disabled_even_if_services_on():+ with patch("app.core.scheduler.settings") as s, \+ patch("app.core.scheduler.AsyncSessionLocal") as sessions, \+ patch("app.core.scheduler.check_services", new_callable=AsyncMock) as check:+ _configure(s, checker=False, services=True)+ await _run_service_checks()+ sessions.assert_not_called()+ check.assert_not_called()+++def test_reschedule_without_a_job_does_not_raise():+ """POST /settings calls this; with no job it used to 500 (JobLookupError)."""+ mock_sched = MagicMock()+ mock_sched.running = True+ mock_sched.get_job.return_value = None+ with patch("app.core.scheduler.scheduler", mock_sched):+ reschedule_status_checks(60)+ mock_sched.reschedule_job.assert_not_called()+++def test_enabling_service_checks_is_refused_when_disabled():+ mock_sched = MagicMock()+ mock_sched.running = True+ mock_sched.get_job.return_value = None+ with patch("app.core.scheduler.scheduler", mock_sched), \+ patch("app.core.scheduler.settings") as s:+ _configure(s, checker=False)+ set_service_checks_enabled(True)+ mock_sched.add_job.assert_not_called()