Skip to content

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

feat(backend): STATUS_CHECKER_ENABLED switch to disable status/service checks

Tom Vaisbortba0ebd816522
diff --git a/.env.example b/.env.example
index da5b10c..4740b63 100644
--- a/.env.example
+++ b/.env.example
@@ -54,6 +54,10 @@ SCANNER_HTTP_VERIFY_TLS=false
# Status checker interval in seconds
STATUS_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.py
index 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 None
node = 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_target
if node_data.status:
diff --git a/backend/app/core/config.py b/backend/app/core/config.py
index 8d43ac1..d6400e8 100644
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@@ -179,6 +179,13 @@ class Settings(BaseSettings):
# Status checker
status_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 = False
diff --git a/backend/app/core/scheduler.py b/backend/app/core/scheduler.py
index 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 the
checks; the broadcast simply carries an empty `node_ids`.
"""
+ if not settings.status_checker_enabled:
+ return
async 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 belong
to 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):
return
from 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")
+ return
scheduler.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")
+ return
job = 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.py
new file mode 100644
index 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 None
diff --git a/backend/tests/test_status_checker_toggle.py b/backend/tests/test_status_checker_toggle.py
new file mode 100644
index 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()