synfull 0.1.2 → 0.1.4

package/README.md

@@ -1,10 +1,30 @@
 # Synfull
 
-Synfull is a local-first host monitoring dashboard for Windows and Linux, providing CPU, memory, disk, network, process, service, integration and host-event views through a browser interface and REST API.
+**Local-first host monitoring for Windows and Linux.** Synfull brings live system metrics, process and service visibility, operational checks, and Docker/PM2 integrations together in a self-hosted dashboard.
 
-## Install from npm
+[![npm version](https://img.shields.io/npm/v/synfull)](https://www.npmjs.com/package/synfull)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Requirements: Node.js 18+, Python 3.10+, and npm. The CLI creates its own Python virtual environment and installs the backend dependencies when needed. On Ubuntu/Debian, install `python3-venv` (or the matching `python3.X-venv` package) if venv creation reports that pip is missing. Linux may also require build prerequisites when a dependency has no wheel for the host platform.
+## What it does
+
+- Live CPU, memory, storage, network, uptime, temperature, and process monitoring.
+- Host service and scheduled-job inventory, system logs, and an administrator audit trail.
+- Optional Docker and PM2 integrations, with container controls and Docker event alerts.
+- Endpoint availability/TLS checks, backup freshness checks, resource history, and thresholds.
+- User accounts, guest permissions, and per-user dashboard themes.
+- A local-first web dashboard with an optional, explicit LAN-access choice.
+
+Synfull is built with a **FastAPI/Python backend** and a **React/Vite frontend**, distributed through npm with a small Node.js CLI.
+
+## Install and run
+
+### Requirements
+
+- Node.js 18 or newer and npm.
+- Python 3.10 or newer. Synfull creates its own virtual environment on first setup.
+- On Ubuntu/Debian, install `python3-venv` (or the matching `python3.X-venv` package) if Python reports that pip/venv support is missing. Some Linux distributions may need build tools when a Python dependency has no prebuilt wheel.
+
+### From npm
 
 ```sh
 npm install -g synfull
@@ -13,47 +33,87 @@ synfull start
 synfull open
 ```
 
-During interactive `synfull setup`, you can choose whether to bind to `0.0.0.0` for access from other devices on your LAN; localhost-only (`127.0.0.1`) remains the default, and non-interactive setup stays local-only. LAN binding exposes the login page and server to every reachable network interface: use a trusted LAN, configure the host firewall to allow only the devices/subnet you intend, change the initial `admin` / `admin` password locally before signing in remotely, and do not expose Synfull directly to the public internet. npm installation alone does not register a background service or change system startup.
+`synfull setup` prepares the Python runtime and dependencies. It asks whether to enable LAN access when run in an interactive terminal; **No/Enter keeps Synfull on `127.0.0.1`**, accessible only from the host. Choosing LAN access binds to `0.0.0.0`; other devices can then connect to `http://<server-lan-ip>:8000`.
+
+The first local login is `admin` / `admin`. Synfull requires a new password of at least 12 characters before allowing access to the dashboard. If you enable LAN access, change this password from the server itself before signing in remotely. Bind only on a trusted LAN, restrict port `8000` with your firewall, and do not expose the service directly to the public internet.
 
 ### Commands
 
-- `synfull setup` asks whether to allow LAN access, then prepares the isolated Python runtime and dependencies. The choice is saved in the CLI config and used by later starts and service registration.
-- `synfull start` runs in the background; `synfull run` keeps the server in the foreground.
-- `synfull status`, `synfull stop`, and `synfull open` manage a manually started instance.
-- `synfull install-service` explicitly enables automatic start and restart. On Windows this registers a per-user logon scheduled task. On Linux it creates and enables a system-wide systemd service and therefore requires `sudo`; the service runs as your invoking user, not root.
-- `synfull uninstall-service` removes startup registration but retains application data.
+| Command | Description |
+| --- | --- |
+| `synfull setup` | Ask setup options and prepare the isolated Python runtime/dependencies. |
+| `synfull start` | Start Synfull in the background. |
+| `synfull run` | Run Synfull in the foreground. |
+| `synfull status` | Show process status, dashboard address, and data location. |
+| `synfull stop` | Stop a background instance. |
+| `synfull open` | Open the dashboard on the local machine. |
+| `synfull install-service` | Explicitly register automatic startup (Windows sign-in task or Linux systemd service). |
+| `synfull uninstall-service` | Remove startup registration; retain application data. |
+
+Service registration is optional and is never performed by npm installation. On Linux, installing or removing the system-wide systemd service requires `sudo`; Synfull runs as the invoking user, not as root.
+
+## Optional integrations and security
+
+### Docker on Linux
+
+During interactive Linux setup, Synfull offers to add your account to the `docker` group so it can access the Docker daemon. This is optional. **Membership in the Docker group grants root-equivalent control of the machine.** Only approve this for an account you trust with administrator-level access.
+
+If the Synfull systemd service is installed, setup restarts it after granting access so it picks up the new group membership. For a manually started instance, log out and back in (or start a new session) before running Synfull again. Docker must be installed and its daemon must be running.
+
+### LAN access
 
-Use the same user account to install/start Synfull and install its startup service. Service registration is optional and is not performed during `npm install -g`.
+The LAN option is deliberately opt-in. `0.0.0.0` listens on every network interface, not just a private LAN interface. Use a trusted network and firewall rules that allow only the devices/subnet you intend. Authentication is required, but the initial password must be rotated locally before remote login.
 
-Configuration:
+## Configuration
 
-- `SYNFULL_HOME` selects the CLI runtime/application directory.
-- `SYNFULL_STATE_DIR` selects persistent database and app state.
-- `SYNFULL_BIND_PORT` changes the port (default `8000`). The bind host is selected during interactive setup and defaults to `127.0.0.1`; `SYNFULL_BIND_HOST=127.0.0.1` or `SYNFULL_BIND_HOST=0.0.0.0` can override it for a single run/service install.
+The CLI stores its runtime and preferences under the user's local application-data directory. Persistent application state is stored separately.
 
-## Development from source
+| Variable | Purpose |
+| --- | --- |
+| `SYNFULL_HOME` | Override the CLI application/runtime directory. |
+| `SYNFULL_STATE_DIR` | Override the directory for persistent database and application state. |
+| `SYNFULL_BIND_PORT` | Change the listening port (default `8000`). |
+| `SYNFULL_BIND_HOST` | Override the bind host for a command/service install: `127.0.0.1` or `0.0.0.0`. Setup's saved choice applies when this is unset. |
 
-The source tree includes a Python FastAPI backend and a React/Vite frontend.
+## Development
+
+Clone the repository, then install the backend and frontend development dependencies.
+
+### Windows PowerShell
 
 ```powershell
 .\scripts\dev.ps1
 ```
 
+### Linux/macOS shell
+
 ```sh
-python -m venv .venv
+python3 -m venv .venv
+. .venv/bin/activate
 python -m pip install -r backend/requirements.txt
 npm --prefix frontend ci
-npm --prefix frontend run build
+npm --prefix frontend run dev
 ```
 
-Run the API from the repository root with `python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000`. Tests: `python -m pytest backend/tests` and `npm --prefix frontend run lint`.
+The Vite development server proxies API requests to the backend. In another terminal, start the API from the project root:
 
-## npm publishing
+```sh
+PYTHONPATH=backend python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
+```
 
-Package metadata and the `synfull` executable live in the repository-root `package.json`. The publish package includes the backend, runtime requirements, CLI and built frontend, not development dependencies. `npm pack --dry-run` can be used to inspect the tarball contents before publishing.
+Build the frontend for production with:
 
-The package name `synfull` was checked against the public npm registry while preparing this release and appeared available. Publishing still requires an npm account with permission to claim/publish the name and should only be done by an authorized maintainer.
+```sh
+npm --prefix frontend run build
+```
+
+Run checks from the project root (with backend development dependencies installed):
+
+```sh
+PYTHONPATH=backend python -m pytest backend/tests
+npm --prefix frontend run lint
+```
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+Synfull is released under the [MIT License](LICENSE).

package/backend/app/api/routes.py

@@ -5,9 +5,11 @@ from fastapi import APIRouter, HTTPException, Query, Request, Response
 from ..collectors.processes import collect_processes
 from ..collectors.system import collect_system_metrics, platform_capabilities
 from ..config import get_settings
-from ..integrations.discord_alerts import public_config as discord_alert_config, send_test_message, update_config as update_discord_alert_config
+from ..integrations.discord_alerts import (public_config as discord_alert_config, public_history_config,
+                                           send_test_message, update_config as update_discord_alert_config,
+                                           update_history_config)
 from ..integrations.status import docker_action, docker_logs, integrations_status
-from ..schemas.alerts import DiscordAlertUpdate
+from ..schemas.alerts import DiscordAlertUpdate, HistoryDiscordAlertUpdate
 from ..schemas.system import ProcessResponse, SystemResponse
 from ..schemas.management import AdminSetup, BackupTargetsUpdate, EndpointTargetsUpdate, LoginPayload, PasswordChange, ServiceAllowlistUpdate, ThresholdUpdate, ThemeUpdate, UserCreate, UserUpdate
 from ..services import management
@@ -175,7 +177,8 @@ def put_discord_alert_config(payload: DiscordAlertUpdate, request: Request):
     try:
         result = update_discord_alert_config(enabled=payload.enabled, webhook_url=webhook_url,
                                              events=payload.events,
-                                             minimum_interval_seconds=payload.minimum_interval_seconds)
+                                             minimum_interval_seconds=payload.minimum_interval_seconds,
+                                             webhook_username=payload.webhook_username, avatar_url=payload.avatar_url)
         management._audit(username=management.require_admin(request), action="docker.alerts.discord.update")
         return result
     except ValueError as exc:
@@ -186,7 +189,7 @@ def put_discord_alert_config(payload: DiscordAlertUpdate, request: Request):
 def test_discord_alert(request: Request):
     management.require_admin(request)
     try:
-        send_test_message()
+        send_test_message("docker")
         management._audit(username=management.require_admin(request), action="docker.alerts.discord.test")
         return {"sent": True, "message": "Test alert sent to Discord."}
     except Exception as exc:
@@ -194,6 +197,42 @@ def test_discord_alert(request: Request):
         raise HTTPException(status_code=503, detail=str(exc)) from exc
 
 
+@router.get("/management/metrics/discord")
+def get_history_discord_config(request: Request):
+    management.require_admin(request)
+    return public_history_config()
+
+
+@router.put("/management/metrics/discord")
+def put_history_discord_config(payload: HistoryDiscordAlertUpdate, request: Request):
+    username = management.require_admin(request)
+    current = public_history_config()
+    webhook_url = "" if payload.clear_webhook else (payload.webhook_url or None)
+    if payload.enabled and not current["configured"] and webhook_url is None:
+        raise HTTPException(status_code=400, detail="Set a Discord webhook URL before enabling alerts")
+    if payload.enabled and webhook_url == "":
+        raise HTTPException(status_code=400, detail="Set a Discord webhook URL before enabling alerts")
+    try:
+        result = update_history_config(enabled=payload.enabled, webhook_url=webhook_url,
+                                       webhook_username=payload.webhook_username, avatar_url=payload.avatar_url)
+        management._audit(username=username, action="monitoring.alerts.discord.update")
+        return result
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/management/metrics/discord/test")
+def test_history_discord_alert(request: Request):
+    username = management.require_admin(request)
+    try:
+        send_test_message("history")
+        management._audit(username=username, action="monitoring.alerts.discord.test")
+        return {"sent": True, "message": "Test alert sent to Discord."}
+    except Exception as exc:
+        management._audit(username=username, action="monitoring.alerts.discord.test", outcome="failed", details=str(exc))
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
 @router.get("/docker/containers/{container_id}/logs")
 def container_logs(container_id: str, request: Request, tail: int = Query(default=300, ge=1, le=2000)):
     management.require_admin(request)

package/backend/app/integrations/discord_alerts.py

@@ -23,6 +23,18 @@ class DiscordAlertConfig(Base):
     enabled = Column(Boolean, nullable=False, default=False)
     events_json = Column(Text, nullable=False, default='{"start":true,"stop":true,"crash":true,"restart":true}')
     minimum_interval_seconds = Column(Integer, nullable=False, default=60)
+    webhook_username = Column(Text, nullable=False, default="Synfull - AIO Monitoring Software")
+    avatar_url = Column(Text, nullable=False, default="https://api.iconify.design/lucide/activity.svg?color=%23ffffff")
+
+
+class HistoryDiscordAlertConfig(Base):
+    __tablename__ = "history_discord_alert_config"
+
+    id = Column(Integer, primary_key=True, default=1)
+    webhook_url = Column(Text, nullable=False, default="")
+    enabled = Column(Boolean, nullable=False, default=False)
+    webhook_username = Column(Text, nullable=False, default="Synfull - Monitoring Alerts")
+    avatar_url = Column(Text, nullable=False, default="https://api.iconify.design/lucide/activity.svg?color=%23ffffff")
 
 
 Base.metadata.create_all(bind=engine)
@@ -31,6 +43,22 @@ DEFAULT_EVENTS = {"start": True, "stop": True, "crash": True, "restart": True}
 EMBED_BLUE = 0x3B82F6
 WEBHOOK_USERNAME = "Synfull - AIO Monitoring Software"
 WEBHOOK_AVATAR_URL = "https://api.iconify.design/lucide/activity.svg?color=%23ffffff"
+HISTORY_WEBHOOK_USERNAME = "Synfull - Monitoring Alerts"
+
+
+def _migrate_docker_config_schema() -> None:
+    from sqlalchemy import inspect
+    columns = {column["name"] for column in inspect(engine).get_columns("discord_alert_config")}
+    with engine.begin() as connection:
+        if "webhook_username" not in columns:
+            connection.exec_driver_sql(
+                "ALTER TABLE discord_alert_config ADD COLUMN webhook_username TEXT NOT NULL DEFAULT 'Synfull - AIO Monitoring Software'")
+        if "avatar_url" not in columns:
+            connection.exec_driver_sql(
+                "ALTER TABLE discord_alert_config ADD COLUMN avatar_url TEXT NOT NULL DEFAULT 'https://api.iconify.design/lucide/activity.svg?color=%23ffffff'")
+
+
+_migrate_docker_config_schema()
 
 
 def _config_from_db() -> DiscordAlertConfig:
@@ -44,6 +72,38 @@ def _config_from_db() -> DiscordAlertConfig:
         return config
 
 
+def _history_config_from_db() -> HistoryDiscordAlertConfig:
+    with SessionLocal() as session:
+        config = session.get(HistoryDiscordAlertConfig, 1)
+        if config is None:
+            config = HistoryDiscordAlertConfig(id=1)
+            session.add(config)
+            session.commit()
+            session.refresh(config)
+        return config
+
+
+def _validate_webhook_url(webhook_url: str) -> str:
+    normalized_url = webhook_url.strip()
+    parsed = urlparse(normalized_url)
+    if (parsed.scheme != "https" or parsed.hostname != "discord.com"
+            or not parsed.path.startswith("/api/webhooks/") or parsed.username or parsed.password):
+        raise ValueError("Enter a valid Discord HTTPS webhook URL")
+    return normalized_url
+
+
+def _validate_identity(webhook_username: str, avatar_url: str) -> tuple[str, str]:
+    username = webhook_username.strip()
+    avatar = avatar_url.strip()
+    if not username or len(username) > 80:
+        raise ValueError("Webhook name must be between 1 and 80 characters")
+    if avatar:
+        parsed = urlparse(avatar)
+        if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
+            raise ValueError("Webhook avatar URL must be a valid HTTPS URL")
+    return username, avatar
+
+
 def _parse_events(raw: str) -> dict[str, bool]:
     try:
         events = json.loads(raw)
@@ -56,10 +116,40 @@ def public_config() -> dict[str, Any]:
     config = _config_from_db()
     masked = "https://discord.com/api/webhooks/••••••••" if config.webhook_url else ""
     return {"enabled": config.enabled, "configured": bool(config.webhook_url), "webhook_url_masked": masked,
+            "webhook_username": config.webhook_username, "avatar_url": config.avatar_url,
             "events": _parse_events(config.events_json), "minimum_interval_seconds": config.minimum_interval_seconds}
 
 
-def update_config(*, enabled: bool, webhook_url: str | None, events: dict[str, bool], minimum_interval_seconds: int) -> dict[str, Any]:
+def public_history_config() -> dict[str, Any]:
+    config = _history_config_from_db()
+    masked = "https://discord.com/api/webhooks/••••••••" if config.webhook_url else ""
+    return {"enabled": config.enabled, "configured": bool(config.webhook_url), "webhook_url_masked": masked,
+            "webhook_username": config.webhook_username, "avatar_url": config.avatar_url}
+
+
+def update_history_config(*, enabled: bool, webhook_url: str | None, webhook_username: str, avatar_url: str) -> dict[str, Any]:
+    username, avatar = _validate_identity(webhook_username, avatar_url)
+    with SessionLocal() as session:
+        config = session.get(HistoryDiscordAlertConfig, 1)
+        if config is None:
+            config = HistoryDiscordAlertConfig(id=1)
+            session.add(config)
+            session.flush()
+        if webhook_url == "":
+            config.webhook_url = ""
+        elif webhook_url is not None:
+            config.webhook_url = _validate_webhook_url(webhook_url)
+        if enabled and not config.webhook_url:
+            raise ValueError("Set a Discord webhook URL before enabling alerts")
+        config.enabled = enabled
+        config.webhook_username = username
+        config.avatar_url = avatar
+        session.commit()
+    return public_history_config()
+
+
+def update_config(*, enabled: bool, webhook_url: str | None, events: dict[str, bool], minimum_interval_seconds: int,
+                  webhook_username: str = WEBHOOK_USERNAME, avatar_url: str = WEBHOOK_AVATAR_URL) -> dict[str, Any]:
     with SessionLocal() as session:
         config = session.get(DiscordAlertConfig, 1)
         if config is None:
@@ -69,27 +159,34 @@ def update_config(*, enabled: bool, webhook_url: str | None, events: dict[str, b
         if webhook_url == "":
             config.webhook_url = ""
         elif webhook_url is not None:
-            normalized_url = webhook_url.strip()
-            parsed = urlparse(normalized_url)
-            if parsed.scheme != "https" or parsed.hostname != "discord.com" or not parsed.path.startswith("/api/webhooks/") or parsed.username or parsed.password:
-                raise ValueError("Enter a valid Discord HTTPS webhook URL")
-            config.webhook_url = normalized_url
+            config.webhook_url = _validate_webhook_url(webhook_url)
+        username, avatar = _validate_identity(webhook_username, avatar_url)
         if minimum_interval_seconds < 0 or minimum_interval_seconds > 3600:
             raise ValueError("Minimum alert interval must be between 0 and 3600 seconds")
         config.enabled = enabled
         config.events_json = json.dumps({key: bool(events.get(key, False)) for key in DEFAULT_EVENTS})
         config.minimum_interval_seconds = minimum_interval_seconds
+        config.webhook_username = username
+        config.avatar_url = avatar
         session.commit()
     return public_config()
 
 
-def send_discord_message(content: str, *, title: str = "Monitoring alert", timeout_seconds: float = 8.0) -> None:
-    config = _config_from_db()
-    if not config.webhook_url:
-        raise ValueError("Configure a Discord webhook URL first")
+def send_discord_message(content: str, *, title: str = "Monitoring alert", timeout_seconds: float = 8.0,
+                         channel: str = "docker") -> None:
+    if channel == "history":
+        config = _history_config_from_db()
+        default_username = HISTORY_WEBHOOK_USERNAME
+        if not config.enabled or not config.webhook_url:
+            raise ValueError("Configure and enable the History & Alerts Discord webhook first")
+    else:
+        config = _config_from_db()
+        default_username = WEBHOOK_USERNAME
+        if not config.webhook_url:
+            raise ValueError("Configure a Discord webhook URL first")
     payload = {
-        "username": WEBHOOK_USERNAME,
-        "avatar_url": WEBHOOK_AVATAR_URL,
+        "username": config.webhook_username or default_username,
+        "avatar_url": config.avatar_url or WEBHOOK_AVATAR_URL,
         "allowed_mentions": {"parse": []},
         "embeds": [{
             "title": title[:256],
@@ -110,7 +207,7 @@ def send_discord_message(content: str, *, title: str = "Monitoring alert", timeo
         raise RuntimeError("Could not reach Discord webhook. Check the connection and webhook URL.") from None
 
 
-def send_test_message() -> None:
+def send_test_message(channel: str = "docker") -> None:
     send_discord_message(
         "\n".join((
             "✅ **Webhook connected successfully**",
@@ -118,6 +215,7 @@ def send_test_message() -> None:
             "Synfull can now deliver monitoring alerts to this channel.",
         )),
         title="Webhook test",
+        channel=channel,
     )
 
 

package/backend/app/schemas/alerts.py

@@ -9,6 +9,8 @@ class DiscordAlertUpdate(BaseModel):
     events: dict[str, bool] = Field(default_factory=lambda: {"start": True, "stop": True, "crash": True, "restart": True})
     minimum_interval_seconds: int = Field(default=60, ge=0, le=3600)
     webhook_url: str | None = None
+    webhook_username: str = "Synfull - AIO Monitoring Software"
+    avatar_url: str = "https://api.iconify.design/lucide/activity.svg?color=%23ffffff"
     clear_webhook: bool = False
 
     @field_validator("events")
@@ -17,3 +19,11 @@ class DiscordAlertUpdate(BaseModel):
         if set(value) != DEFAULT_DOCKER_ALERT_EVENTS:
             raise ValueError("Choose a value for each supported Docker alert event")
         return value
+
+
+class HistoryDiscordAlertUpdate(BaseModel):
+    enabled: bool
+    webhook_url: str | None = None
+    webhook_username: str = Field(default="Synfull - Monitoring Alerts", min_length=1, max_length=80)
+    avatar_url: str = "https://api.iconify.design/lucide/activity.svg?color=%23ffffff"
+    clear_webhook: bool = False

package/backend/app/services/management.py

@@ -350,6 +350,8 @@ def _permission_for_request(request) -> str | None:
     if path == "capabilities": return "view_dashboard"
     if path == "docker/alerts/discord": return "manage_alerts" if method in {"PUT", "POST"} else "view_alerts"
     if path == "docker/alerts/discord/test": return "manage_alerts"
+    if path == "management/metrics/discord": return "manage_alerts" if method == "PUT" else "view_alerts"
+    if path == "management/metrics/discord/test": return "manage_alerts"
     if path.startswith("docker/containers/"):
         return "manage_docker" if method == "POST" else "view_docker"
     if path.startswith("management/users"): return "view_security"
@@ -980,9 +982,9 @@ def collect_monitoring_sample() -> None:
         session.commit()
     for title, message in notifications:
         try:
-            from ..integrations.discord_alerts import public_config, send_discord_message
-            if public_config()["enabled"]:
-                send_discord_message(message, title=title)
+            from ..integrations.discord_alerts import public_history_config, send_discord_message
+            if public_history_config()["enabled"]:
+                send_discord_message(message, title=title, channel="history")
         except Exception as exc:
             logger.debug("Metric alert notification unavailable: %s", exc)
 
@@ -1004,8 +1006,8 @@ def run_configured_checks() -> None:
             continue
         if result["status"] == "unhealthy" or (result.get("tls_days_remaining") is not None and result["tls_days_remaining"] <= 30):
             try:
-                from ..integrations.discord_alerts import public_config, send_discord_message
-                if public_config()["enabled"]:
+                from ..integrations.discord_alerts import public_history_config, send_discord_message
+                if public_history_config()["enabled"]:
                     send_discord_message(
                         "\n".join((
                             f"⚠️ **Endpoint:** {target['name']}",
@@ -1014,6 +1016,7 @@ def run_configured_checks() -> None:
                             f"**Details:** {result['message']}",
                         )),
                         title="Endpoint health alert",
+                        channel="history",
                     )
             except Exception as exc:
                 logger.debug("Endpoint alert notification unavailable: %s", exc)