# LogForge Overview
LogForge gives self-hosted teams real-time visibility into Docker workloads, rule-based alerting, and guardrailed remediation from a single UI. The platform is made of four collaborating services plus a Watchtower-based auto-updater:

| Component | Role | Key Responsibilities |
|-----------|------|----------------------|
| **LogForge Backend** | Core API & orchestrator | Discovers containers, streams logs, executes safe actions, stores configuration, and exposes REST/WebSocket interfaces consumed by the frontend. |
| **LogForge Frontend** | Unified dashboard | Provides the operator UI for inventory, live logs, rule authoring, automation, and settings. Built with Vite/React. |
| **Alert Engine Backend** | Rule evaluation & automation | Persists alert definitions, evaluates conditions (keywords, container events, trends), coordinates remediation workflow, and produces audit history. |
| **Alert Engine Frontend** | Rich alert authoring UI | Offers advanced rule builders, visualizations, and alert history insights. |
| **Notifier** | Outbound delivery hub | Handles channel integrations (email, Slack, Discord, Telegram, Gotify, webhooks, etc.) with retry/backoff semantics. |
| **Autoupdate** | Watchtower-based updater | Optional container that keeps services on the latest tagged image while respecting scheduling guardrails. |

## How the pieces talk

![Rendered C4 Container Diagram](https://github.com/log-forge/logforgeweb/blob/main/assets/c4diagram-logforge.png?raw=1)

**Socket usage:** In the core edition, only the source-available LogForge Backend mounts `/var/run/docker.sock`, making it the trusted control plane for container discovery, log streaming, and lifecycle actions. The optional `logforge-autoupdate` (Watchtower) also touches the socket solely to pull & restart containers when updates are available. Alert Engine components communicate exclusively over HTTP/WebSockets with the backend and never access the Docker daemon directly.

## Core capabilities at a glance
- **Service awareness**: Auto-discovers any container on the host, grouping them by project or team. Supports explicit ignore lists and manual grouping.
- **Live observability**: Streams logs with filtering, tail controls, and bookmarking. Shows status (running/stopped/crashed) in real time.
- **Rules & alerts**: Keyword matching, frequency/threshold windows, and container lifecycle triggers. Templates make common policies a click away.
- **Safe automation**: Built-in guardrails (cooldowns, rate limits, verification delays, explicit scopes) ensure restarts or scripts do not spiral.
- **Auditability**: Persistent history for alerts, actions taken, user acknowledgements, and delivery status.
- **Extensibility**: Source-available core means you can inspect or extend backend behavior. Premium tiers unlock remote agents, RBAC, Swarm/Kubernetes support, and more.

## Typical deployments
- **Single-host developer workstation**: Run via `docker compose up` and keep everything bound to `127.0.0.1` for local-only management.
- **Production server**: Use an HTTPS reverse proxy (Traefik, Caddy, Nginx), enforce SSO or OAuth, and segment the Docker socket behind a proxy. Recommended for small teams.
- **Hybrid / remote agents** (Premium): Pair onsite LogForge with lightweight agents that ship logs/events securely without exposing Docker sockets remotely.

## When to choose LogForge
LogForge shines when you need:
- Container visibility without installing massive observability stacks.
- Alerting that responds to container health, log patterns, and custom signals in minutes.
- Safe automation that your team can trust not to reboot prod endlessly.
- A self-hosted solution that respects data boundaries.

Use the rest of the wiki to dive into setup, security, automation, and troubleshooting scenarios.