Skip to content

LogForge Core

Jump to bottom
Adan edited this page Oct 6, 2025 · 1 revision

The LogForge Core service is the central control plane that discovers Docker containers, streams their telemetry, and exposes APIs consumed by the Alert Engine and Notifier. It runs alongside two supporting containers: a React frontend (logforge-frontend) and an optional Watchtower-based auto-updater (logforge-autoupdate). The backend is shipped as source-available code so teams can audit or extend it for maximum transparency (see the logforge-core repository).

Responsibilities

  • Discover running containers through the Docker socket and keep an in-memory registry up to date.
  • Collect logs and metadata, exposing them via HTTP and WebSocket endpoints for the dashboards.
  • Manage user-defined container groups (stored in SQLite) so rules and views can target related services.
  • Provide REST APIs that the Alert Engine and Notifier use for container snapshots, groups, config, and health.
  • Broadcast container and group changes in real time to any connected UI or automation client.

Architecture

  • logforge-backend: Python FastAPI application with direct /var/run/docker.sock access. Handles discovery, APIs, WebSockets, and persistence.
  • logforge-frontend: Vite/React UI that calls the backend APIs and listens for WebSocket updates.
  • logforge-autoupdate (optional): Watchtower derivative that tracks container updates when AUTO_UPDATE=true.
  • All services share the logforge-network bridge network; UI ports bind to 127.0.0.1 by default for local access only.

Key APIs (partial)

Endpoint Method Description
/containers GET Returns the cached container list plus monitored groups.
/groups GET/POST/PATCH/DELETE CRUD operations for container groups.
/config/preferences GET/POST UI preferences (timezone, etc.).
/config/filters/add-keyword POST Manage core keyword filters.
/health GET Summarises container counts, rule counts, and DB status.

Refer to logforge/backend/app/routes for the full FastAPI router definitions.

WebSocket channels

  • /ws/logs/{container_name}: streams live logs for an individual container.
  • /ws/updates/{type}: unified feed for config, alerts, containers, or all update types.
  • /ws/updates/alerts/{container}: per-container alert stream (newer alternative to the unified channel).
  • /ws/updates/containers: broadcasts container and group snapshots whenever the registry changes.

Group management workflow

  1. Users create or edit groups via the Core UI; changes hit /groups on the backend.
  2. Groups persist in the Core SQLite database (logforge_core_data volume) using the Group and GroupMembership tables (app/models/settings.py).
  3. When groups or containers change, the backend rebuilds the monitored list and pushes updates to WebSocket subscribers.
  4. The Alert Engine listens to the same WebSocket feed, filters out groups without monitored containers, and surfaces the result in its rule builder scope pickers.

Interaction with other services

  • Alert Engine: Polls /containers and /groups, receives WebSocket updates, and calls /alerts/ingest to push alert metadata back into Core.
  • Notifier: Core exposes configuration endpoints; notifier destinations are managed independently but Core references the notifier container for test sends.
  • Auto-updater: Optional service that restarts containers when new images are available, respecting the AUTO_UPDATE flag.

Persistence and volumes

  • logforge_core_data: stores the Core SQLite database (container registry, groups, UI settings).
  • The backend writes only to this volume; application code lives in the container image.

Security considerations

  • The backend has full Docker control through the socket; protect it with network boundaries or a docker-socket-proxy if you need fine-grained API whitelisting.
  • UI ports bind to loopback by default; use a reverse proxy with TLS and authentication when exposing the dashboard outside the host.
  • Keep credentials (SMTP, webhooks, tokens) in environment variables or Docker secrets rather than the compose file.

Related documentation

Clone this wiki locally