## Prerequisites
- Docker 20.10+
- Docker Compose V2 (`docker compose` CLI)
- 2 CPU cores and 2 GB RAM minimum (4 GB recommended for heavy log throughput)
- Outbound network access for whichever notification channels you plan to use

## 1. Clone and configure

```bash
git clone https://github.com/log-forge/logforge.git
cd logforge
cp .env.example .env  # adjust container names, ports, notification secrets
```

Key `.env` values:

| Variable | Purpose | Default |
|----------|---------|---------|
| `LOGFORGE_FRONTEND_PORT` | Host port for the core UI | `3008` |
| `NOTIFIER_WEB_PORT` | Notifier admin/API port | `8087` |
| `ALERT_ENGINE_FRONTEND_PORT` | Alert Engine UI port | `3033` |
| `AUTO_UPDATE` | Enables the Watchtower auto-updater | `true` |

### Verify host exposure (recommended)
The shipping compose file already binds UI services to loopback so only the host can reach them. If you customise ports or add new services, keep the `127.0.0.1:HOST:CONTAINER` pattern (or front them with a secured reverse proxy) before exposing them to other networks.

## 2. Launch the stack

```bash
docker compose up -d --build
```

The build step compiles the frontend applications; omit `--build` when starting from published images or subsequent restarts.

Verify health:

```bash
docker compose ps
docker compose logs logforge-backend --follow
```

When healthy, browse to `http://localhost:3008` (or the loopback port you set) to access the UI.

## 3. First-time configuration
1. **Discover containers** - the backend auto-detects running containers. Use the inventory view to group or ignore services.
2. **Add notification channels** - open the Notifier UI and configure SMTP, webhooks, or chat connectors. Store secrets in `.env` or Docker secrets.
3. **Author rules** - visit the Alert Engine UI to create policies from templates (crash detection, log keywords, performance thresholds, etc.).
4. **Test a notification** - send a test alert from the Alert Engine to validate delivery.

## Production guidance
- **Reverse proxy**: Terminate TLS with Traefik, Caddy, or Nginx. Protect the UIs with Basic Auth, OAuth, or your IdP of choice.
- **Secrets management**: Replace plain-text credentials with Docker secrets or environment variables injected by your orchestrator.
- **Docker socket access**: If the backend needs socket access, place a [`docker-socket-proxy`](https://github.com/Tecnativa/docker-socket-proxy) sidecar in front of `/var/run/docker.sock` and allow only the capabilities you require.
- **Logging**: Persist container logs using a driver (json-file rotation) or forward to an external sink alongside LogForge dashboards.
- **Backups**: Persistent data resides in the named volumes `logforge_core_data`, `logforge_notifier_data`, and `logforge_alert_engine_data`. Snapshot them regularly.

## Upgrades
1. Pull the latest repo changes or switch to the desired tag.
2. Restart with `docker compose pull && docker compose up -d` (or rebuild from source for development installs).
3. Watch the Alert Engine and backend logs for schema migration messages.

With `AUTO_UPDATE=true`, Watchtower automatically tracks published container updates. For controlled rollouts, disable auto-update and perform the manual steps above.

## Next steps
- Dive into the [Alert Engine Guide](Alert-Engine.md) to craft effective rules.
- Connect delivery channels via the [Notifier & Integrations](Notifier-Integrations.md) reference.
- Lock down your deployment using the [Security & Hardening](Security.md) checklist.