### Start LoggiFly with Systemd

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/podman.md

Command to start the LoggiFly container managed by a Podman quadlet file using systemd user services.

```bash
systemctl --user start loggifly
```

--------------------------------

### LoggiFly Environment Variables for Quick Start

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

Use these environment variables in your docker-compose file for a minimal LoggiFly setup. Ensure at least one notification service URL is configured.

```yaml
    environment:
      # Choose at least one notification service
      NTFY_URL: "https://ntfy.sh"
      NTFY_TOPIC: "your_topic"
      # ntfy token or username + password for authentication
      NTFY_TOKEN: <token>
      NTFY_USERNAME: <username>
      NTFY_PASSWORD: <password>
      APPRISE_URL: "discord://..."        # Apprise-compatible URL

      CONTAINERS: "vaultwarden,audiobookshelf"   # comma-separated container names to monitor
      GLOBAL_KEYWORDS: "error,failed login"  # keywords applied to all monitored containers
```

--------------------------------

### Loggifly Configuration Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/examples.md

An example Loggifly configuration file showcasing real-world use cases. This serves as a template for defining monitoring rules and settings.

```yaml
containers:
  rules:
    - container_name: fluentbit
      keywords:
        - all_of: 
            - keyword: ssh
            - keyword: failed
            - keyword: password
          title_template: 'Failed SSH Login Attempt'
          message_template: '{{ MESSAGE }}' # this is a field available in the JSON log entry
          trigger_cooldown: 0
          ntfy_tag: rotating_light
```

--------------------------------

### Multi-Rule Merging Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This example demonstrates how configurations from global settings, source-level defaults, and multiple rules are merged for a container. For 'web-app', the effective configuration combines keywords from all levels and uses the highest 'trigger_cooldown' value.

```yaml
global:
  keywords:
    - keyword: "critical"          # global-level: applied to every matched target across all sources (containers and swarm)
  defaults:
    ntfy_priority: 1

containers:
  keywords:
    - keyword: "warning"          # source-level: applies to every matched container

  rules:
    - container_name: "*"  # matches all containers
      trigger_cooldown: 10
      keywords:
        - keyword: "error"            # applies to all containers

    - container_name: web-app  # also matches web-app
      trigger_cooldown: 30             # last match → wins over 10
      keywords:
        - keyword: "timeout"
```

--------------------------------

### Rule Scope and Matching Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This example demonstrates how to define rules that apply to specific hosts and match container names using glob patterns. The 'db-only-on-dbhost' rule applies only to 'db-host' and matches PostgreSQL containers, while 'all-hosts-web' matches all 'web-*' containers.

```yaml
containers:
  rules:
    - id: db-only-on-dbhost
      scope:
        hosts: ["db-host"]        # only applies on db-host
      match:
        include:
          container_names: ["*postgres*"]
      keywords:
        - keyword: "deadlock"

    - id: all-hosts-web
      match:
        include:
          container_names: ["web-*"]
      keywords:
        - keyword: "error"
```

--------------------------------

### Detailed Rule Structure Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This comprehensive example showcases the full structure of a container monitoring rule. It includes optional fields like 'id' and 'enabled', detailed 'scope' and 'match' criteria, various 'keywords' and 'container_events', and settings like 'trigger_cooldown' and 'attach_logfile'.

```yaml
- container_name: my-app
      keywords:
        - keyword: "error"

    # full rule structure
    - id: my-rule          # optional; auto-generated as "rule-1", "rule-2" if omitted
      enabled: true        # default true; set false to disable without removing
      scope:
        hosts: ["host1"]   # optional; if omitted, applies to all hosts
      match:                # this is where you define the matching criteria. 
        include:
          container_names: ["web-*", "api-*"]
        exclude:
          container_names: ["*-test"]
      keywords:
        - "critical" 
        - keyword: "error"
        - regex: "login.*failed"
      container_events:
        - event: crash
        - event: oom
      trigger_cooldown: 30  # any defaults field can be set at rule level
      attach_logfile: true
```

--------------------------------

### v2 Full Configuration Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

A complete configuration file for Loggifly v2, showcasing the updated structure, renamed fields, and Jinja2 templating syntax.

```yaml
version: 2

global:
  defaults:
    trigger_cooldown: 5                # was notification_cooldown; v2 default is 0
    container_action_cooldown: 300     # was action_cooldown; v2 default is 60
    hide_full_regex: true              # was hide_regex_in_title
    regex_case_sensitive: false        # v2 default is true
    ignore_keywords:                   # was excluded_keywords
      - keyword: debug
    merge_matches: true                # v2 default is false; restores v1 behavior

  keywords:                            # was global_keywords.keywords
    - keyword: "critical"

containers:
  never_monitor:
    container_names: ["loggifly"]      # was settings.excluded_containers

  rules:
    - container_name: vaultwarden
      ntfy_tags: "closed_lock_with_key"
      ntfy_priority: 5
      ntfy_topic: security
      keywords:
        - regex: '(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}).*Username or password is incorrect. Try again. IP: (?P<ip>\d{1,3}(?:\.\d{1,3}){3}). Username: (?P<email>[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})'
          message_template: |
            Failed login!
            Email: '{{ email }}'
            IP Address: {{ ip }}
            Time: {{ timestamp }}
          title_template: "Failed Vaultwarden login"  # {variable} → {{ variable }}
          ntfy_tags: "rotating_light"
      container_events:
        - event: crash
          container_action: restart    # was action

  # groups of rules sharing the same scope, replaces the hosts: block
  groups:
    - scope:
        hosts: ["nas"]
      rules:
        - container_name: postgres
          keywords:
            - keyword: "FATAL"
            - keyword: "could not connect"
        - container_name: nginx
          keywords:
            - keyword: "upstream timed out"

swarm:                                 # was swarm_services
  rules:
    - service_name: app_worker
      keywords:
        - keyword: "timeout"
        - keyword: "connection refused"

notifications:
  ntfy:
    url: "http://ntfy.example.com"
    topic: "alerts"
```

--------------------------------

### v1 Full Configuration Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

A complete configuration file for Loggifly v1, demonstrating various settings including global keywords, container-specific rules, and notification settings.

```yaml
settings:
  excluded_containers: ["loggifly"]
  notification_cooldown: 5
  action_cooldown: 300
  hide_regex_in_title: true
  regex_case_sensitive: false
  excluded_keywords:
    - keyword: debug

global_keywords:
  keywords:
    - keyword: "critical"

hosts:
  nas:
    containers:
      postgres:
        keywords:
          - keyword: "FATAL"
          - keyword: "could not connect"
      nginx:
        keywords:
          - keyword: "upstream timed out"

containers:
  vaultwarden:
    ntfy_tags: "closed_lock_with_key"
    ntfy_priority: 5
    ntfy_topic: security
    keywords:
      - regex: '(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}).*Username or password is incorrect. Try again. IP: (\d{1,3}(?:\.\d{1,3}){3}). Username: ([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})'
        message_template: |
          Failed login!
          Email: '{2}'
          IP Address: {3}
          Time: {1}
        title_template: "Failed Vaultwarden login"
        ntfy_tags: "rotating_light"
    container_events:
      - event: crash
        action: restart

swarm_services:
  app_worker:
    keywords:
      - keyword: "timeout"
      - keyword: "connection refused"

notifications:
  ntfy:
    url: "http://ntfy.example.com"
    topic: "alerts"
```

--------------------------------

### Template Output Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/json.md

This shows the expected output after applying the template to the nested JSON log entry.

```text
User admin logged in from Berlin
Role: superuser
```

--------------------------------

### Docker Compose Healthcheck Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/healthcheck.md

Example Docker Compose configuration enabling and setting up a healthcheck for LoggiFly. It checks LoggiFly's health every 60 seconds.

```yaml
version: "3.8"
services:
  loggifly:
    image: loggifly/loggifly:latest
    ports:
      - "8080:8080"
    environment:
      - ENABLE_HEALTHCHECK=true
    healthcheck:
      test: ["CMD", "/usr/bin/curl", "--fail", "http://localhost:8080/healthcheck"] # or "CMD-SHELL" if curl is not in the image
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 30s
```

--------------------------------

### Trigger Merging Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/keywords-and-triggers.md

Demonstrates how global, source, and rule-level triggers are combined. Most specific level settings are prioritized.

```yaml
global:
  keywords:
    - "critical" # applied to every matched target across all sources (containers and swarm)

containers:
  keywords:
    - keyword: "panic" # applied to every container matched by any rule

  container_events:
    - event: crash # applied to every container matched by any rule

  rules:
    - container_name: my-app
      keywords:
        - keyword: "error" # applied only to containers matched by this rule
      container_events:
        - event: start # applied only to containers matched by this rule

swarm:
  rules:
    - service_name: my-service
      keywords:
        - keyword: "timeout" # applied only to services matched by this rule
```

--------------------------------

### Optional Podman Run Options

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/podman.md

These options may be required depending on your Podman setup, particularly concerning SELinux or user ID mapping.

```bash
  --security-opt label=disable \  # only necessary if SElinux prohibits the access of sockets from inside the container
```

```bash
  --user 1000:1000 \              # might be necessary depending on your setup
```

--------------------------------

### Global Defaults Configuration Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/global.md

This snippet shows the structure and available settings within the `defaults:` section of the `config.yaml` file. It covers behavioral defaults, templating, and integration settings.

```yaml
global:

  defaults:

    # --- Behavioral defaults ----------------------------------------------

    # Minimum seconds between repeated triggers for the same keyword on the
    # same target. 0 = no cooldown (default).
    trigger_cooldown: 0

    # Minimum seconds between repeated container actions on the same target.
    # Default: 60. Minimum enforced: 10.
    container_action_cooldown: 60

    # Attach recent log lines as a file to the notification.
    attach_logfile: false
    attachment_lines: 20                # number of lines to include

    # Hide the full regex pattern in the notification title.
    # Useful for long/complex patterns.
    hide_full_regex: false

    # Regex patterns are case-sensitive by default.
    regex_case_sensitive: true

    # Suppress notifications from triggers (eg. keyword matches) entirely.
    # Useful for action-only workflows where you don't need the notification.
    disable_trigger_notifications: false

    # When a single log line matches multiple keywords, send one notification
    # per keyword match (false, default) or merge into one notification (true).
    merge_matches: false

    # Keywords/patterns that suppress a trigger when found in the same log line.
    # Accepts plain strings, { keyword: ... }, and { regex: ... }.
    # Combined with ignore_keywords from all other levels.
    ignore_keywords:
      - debug
      - keyword: trace
      - regex: ^\[HEALTH\]


    # --- Templates --------------------------------------------------------
    # Jinja2 syntax: {{ variable }}. Variable names listed in the docs:
    # https://clemcer.github.io/loggifly/guide/customize-notifications/

    title_template: "{{ container_name }}: {{ keywords }}"
    message_template: |
      Container: {{ container_name }}
      Keywords:  {{ keywords }}
      Time:      {{ datetime }}
      Log:       {{ log_entry }}

    # --- OliveTin integration ---------------------------------------------
    olivetin_url: "http://olivetin:1337"
    olivetin_username: "admin"
    olivetin_password: "secret"

    # --- Notification channel settings ------------------------------------
    # Rarely set here since the notifications section already handles the global settings
    # However, you can set these per rule or trigger as well to override the global settings
    # ntfy_url:
    # ntfy_topic:
    # ntfy_priority:
    # ntfy_tags:
    # ntfy_token:
    # ntfy_username:
    # ntfy_password:
    # ntfy_icon:
    # ntfy_click:
    # ntfy_markdown:
    # ntfy_actions:
    # ntfy_headers:
    # apprise_url:
    # webhook_url:
    # webhook_headers:

```

--------------------------------

### Example JSON Log Entry

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/json.md

This is a sample JSON log entry from Authelia that demonstrates a typical error structure.

```json
{
  "level": "error",
  "method": "POST",
  "msg": "Unsuccessful 1FA authentication attempt by user 'example_user' and they are banned until 12:23:00PM on May 1 2025 (+02:00)",
  "path": "/api/firstfactor",
  "remote_ip": "192.168.178.191",
  "stack": [
    {
      "File": "github.com/authelia/authelia/v4/internal/handlers/response.go",
      "Line": 274,
      "Name": "doMarkAuthenticationAttemptWithRequest"
    },
    {
      "File": "runtime/asm_amd64.s",
      "Line": 1700,
      "Name": "goexit"
    }
  ],
  "time": "2025-05-01T14:19:29+02:00"
}
```

--------------------------------

### Run Migration Script Directly (Python)

Source: https://github.com/clemcer/loggifly/blob/main/scripts/README.md

Execute the Python migration script from the project root. Requires Python 3.11+ and installed dependencies.

```bash
python scripts/v2_migration/convert.py -i /path/to/config.yaml -o /path/to/output.yaml
```

--------------------------------

### Per-Trigger Settings Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/keywords-and-triggers.md

Demonstrates overriding global default settings for specific keywords and container events within a container rule. This allows fine-grained control over individual triggers.

```yaml
global:
  defaults:
    ntfy_priority: 1
    attach_logfile: false

containers:
  rules:
    - container_name: my-app
      keywords:
        - keyword: error
          ntfy_priority: 5          # override priority for this keyword only
          attach_logfile: true
          trigger_cooldown: 60
          title_template: "Error in my-app"

        - regex: 'panic.*goroutine'
          ntfy_topic: "critical-alerts"
          container_action: restart  # see Actions guide

      container_events:
        - event: crash
          ntfy_priority: 5
          attach_logfile: true
          title_template: "Container {{ container_name }} crashed"
```

--------------------------------

### Global Settings Inheritance Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/global.md

This YAML snippet demonstrates how 'ntfy_priority' is inherited and overridden across global, container, rule, and keyword levels.

```yaml
global:
  defaults:
    ntfy_priority: 1

containers:
  defaults:
    ntfy_priority: 2 # overrides the global level

  # rule level
  rules:
    - container_name: my-app
      ntfy_priority: 3 # overrides the source level
      keywords:
        - keyword: "error"
          ntfy_priority: 5 # overrides the rule level

    # inherits from source.defaults: ntfy_priority: 2
    - container_name: my-other-app
      keywords:
        - keyword: "critical"

swarm:
  rules:
    # inherits from global.defaults: ntfy_priority: 1
    - service_name: my-service
      keywords:
        - keyword: "critical"
```

--------------------------------

### Disabling a Rule Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This example shows how to disable a specific rule using the 'enabled: false' field. The 'debug-rule' will not be active, meaning containers matching its criteria will not be monitored.

```yaml
containers:
  rules:
    - id: debug-rule
      enabled: false       # disabled, containers matched here won't be monitored
      container_name: noisy-app
      keywords:
        - keyword: error
```

--------------------------------

### Fields Available in Container Groups

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This example outlines the various configuration fields that can be included within a container group, mirroring those available in the main `containers:` source block, excluding nested groups.

```yaml
containers:
  groups:
    - scope: ...          # restrict this group to specific hosts
      never_monitor: ...  # exclusion list for this group only
      defaults: ...       # overrides global & source defaults for targets in ghis group
      keywords: [...]     # applied to every matched container from this group
      container_events: [...] # applied to every matched container from this group
      rules: [...]        # Required. At least one rule
```

--------------------------------

### Basic Notification Template

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/index.md

Example of a basic notification template for container logs, specifying rules for matching containers and defining title and message templates.

```yaml
containers:
  rules:
    - container_name: nginx
      keywords:
        - keyword: error
          title_template: "🚨 Error in {{ container_name }}"
          message_template: |
            Log: {{ log_entry }}
            Time: {{ datetime }}
```

--------------------------------

### Example Nested JSON Log Entry

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/json.md

This JSON log entry includes nested structures for user information, roles, and location.

```json
{
  "event": "login",
  "user": {
    "name": "admin",
    "roles": [
      {"name": "superuser"},
      {"name": "editor"}
    ]
  },
  "location": {
    "city": "Berlin",
    "country": "Germany"
  }
}
```

--------------------------------

### Docker Compose with tecnativa/docker-socket-proxy

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

This Docker Compose setup uses the tecnativa/docker-socket-proxy for enhanced security when exposing the Docker socket to LoggiFly.

```yaml
<<< @/compose/compose.tecnativa-proxy.yaml{yaml}
```

--------------------------------

### Notification Template for Container Events

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/index.md

Example template for container events like crashes, using event-specific fields such as exit code and Docker image.

```yaml
containers:
  rules:
    - container_name: app
      container_events:
        - event: crash
          title_template: "Container {{ target_name }} crashed"
          message_template: |
            Exit code: {{ exit_code }}
            Image: {{ docker_image }}
            Time: {{ datetime }}
```

--------------------------------

### Top-Level Keys in config.yaml

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/index.md

This snippet shows the main top-level keys that can be present in the LoggiFly configuration file (config.yaml). These keys define different aspects of the application's setup.

```yaml
version: 2
global:
containers:
swarm:
notifications:
settings:
```

--------------------------------

### Scope Individual Rules to Specific Hosts

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/remote-hosts.md

Apply host-specific scoping to individual container rules. This example monitors 'my-app' on 'host1' and 'host2', 'my-other-app' on 'host3', and all containers on 'host1' and 'host3' for 'critical' keywords.

```yaml
containers:
  rules:
    # only monitor my-app on hosts 1 and 2
    - container_name: my-app
      scope:
        hosts:
          - "host1"
          - "host2"
      keywords:
        - keyword: "error"

    # only monitor my-other-app on host3
    - container_name: my-other-app
      scope:
        hosts: ["host3"]
      container_events:
        - event: crash

    # monitor all containers on hosts 1 and 3 for "critical"
    - container_name: "*"
      scope:
        hosts: ["host1", "host3"]
      keywords:
        - keyword: "critical"
```

--------------------------------

### Example of Container Groups with Shared Keywords and Overrides

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This snippet demonstrates how to define a group of containers that share common configurations like scope and keywords. Individual rules within the group can override inherited settings, such as `trigger_cooldown`.

```yaml
containers:
  groups:
    - scope:
        hosts: ["my-remote-host"]
      trigger_cooldown: 30
      never_monitor:
        container_names: ["*-test"]
      keywords:
        - keyword: "connection refused"   # applied to every rule in this group

      rules:
        - container_name: my-app
          keywords:
            - keyword: error
        - container_name: my-other-app
          trigger_cooldown: 60            # overrides the group's 30
          keywords:
            - keyword: warning
```

--------------------------------

### Custom ntfy Headers Example

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/notifications.md

This snippet demonstrates how to set custom HTTP headers for ntfy notifications. The 'At' header can be used to schedule notifications for a specific time, and other custom headers can be added as needed.

```yaml
headers:
  At: "tomorrow, 10am" # ntfy delay feature. send the notification at 10am tomorrow
  X-Custom-Header: "Test123" # custom header
```

--------------------------------

### Run LoggiFly with Podman (Rootless)

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/podman.md

Use this command to run LoggiFly as a rootless container with Podman. Ensure the user namespace and socket mounts are correctly configured.

```bash
podman run -d \
  --name loggifly \
  --userns keep-id:uid=1000,gid=1000 \
  -v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock \
  -v /path/to/config.yaml:/config/config.yaml \
  -e DOCKER_HOST=unix:///run/user/1000/podman/podman.sock \
  -e CONTAINERS="container1,container2" \
  -e GLOBAL_KEYWORDS="error,critical" \
  ghcr.io/clemcer/loggifly:latest
```

--------------------------------

### Container Configuration with Docker Labels

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/label-config.md

Demonstrates how to configure various Loggifly settings for a container using Docker labels. This includes enabling monitoring, setting notification URLs, keywords, ignore keywords, and specific event configurations.

```yaml
services:
  container1:
    image: my-container
    labels:
      loggifly.monitor: "true" # has to be set

      # container-level settings
      loggifly.apprise_url: "discord://webhook-url"
      loggifly.ntfy_tags: "closed_lock_with_key"
      loggifly.ntfy_priority: "3"
      loggifly.attach_logfile: "true" # always attach the logfile to the notification for this container

      # comma-separated lists for keywords and ignore keywords on container level
      loggifly.keywords: "keyword1,keyword2,keyword3"
      loggifly.ignore_keywords: "keyword4,keyword5,keyword6"
      
      # simple keyword with notification title
      loggifly.keywords.0: "critical" 
      loggifly.keywords.0.title_template: "{container}: Critical Alert"
      
      # regex with ntfy tags
      loggifly.keywords.1.regex: 'download.*failed' 
      loggifly.keywords.1.ntfy_tags: "partying_face"
      
      # simple keyword with container_action
      loggifly.keywords.2.keyword: "timeout" 
      loggifly.keywords.2.container_action: "restart"

      # comma-separated list of container events
      loggifly.container_events: "oom,die,destroy"

      # container event with container_action and title_template
      loggifly.container_events.0.event: "crash"
      loggifly.container_events.0.container_action: "restart"
      loggifly.container_events.0.title_template: "{container} crashed with exit code {exit_code}"

  
```

--------------------------------

### Custom Configuration File Path

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Demonstrates how to specify a custom configuration file path using the `CONFIG_PATH` environment variable in v2.

```yaml
environment:
  CONFIG_PATH: /config/my-custom-config.yaml
```

--------------------------------

### Podman Quadlet File for LoggiFly

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/podman.md

Configure LoggiFly as a systemd service using a Podman quadlet file for rootless execution. This allows for automatic updates and persistent running.

```ini
[Unit]
Description=Loggifly container
Wants=network-online.target
After=network-online.target

[Container]
ContainerName=loggifly
Image=ghcr.io/clemcer/loggifly:latest
AutoUpdate=registry # auto update of image, podman-auto-update.timer needs to run for it to work
Environment=CONTAINERS="container1,container2"
Environment=GLOBAL_KEYWORDS="error,failed login,password"
Environment=APPRISE_URL=<apprise url>
Environment=DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
Volume=/path/to/config:/config
Volume=/run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock
UserNS=keep-id:uid=1000,gid=1000 
#User=1000:1000            # might be necessary depending on your setup
#SecurityLabelDisable=true # only necessary if SElinux prohibits the access of sockets from inside the container

[Service]
Restart=always

[Install]
WantedBy=multi-user.target default.target # default target is only necessary if a start at boot is desired

```

--------------------------------

### Run Migration Script with Docker (Default Paths)

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Execute the Loggifly v1 to v2 migration script using Docker with default configuration paths. The script reads from /config/config.yaml and writes to /config/configv2.yaml within the container, leaving your original file untouched.

```bash
docker run --rm \
  -v /path/to/your/config/dir:/config \
  ghcr.io/clemcer/loggifly-migrate:v1-to-v2
```

--------------------------------

### Extracting JSON Fields with message_template

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/customize-notifications/json.md

Use `message_template` and `title_template` to extract and display specific fields from JSON logs. This example shows how to format a failed login alert.

```yaml
containers:
  rules:
    - container_name: authelia
      keywords:
        - keyword: Unsuccessful 1FA authentication
          title_template: "Failed login from {{ remote_ip }}"
          message_template: |
            🚨 Failed Login Attempt:
            {{ msg }}
            🔎 IP: {{ remote_ip }}
            🕐 {{ time }}
```

--------------------------------

### Configuring Swarm Services in config.yaml

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/swarm.md

This configuration snippet shows how to define Swarm services for LoggiFly monitoring within the `config.yaml` file. It demonstrates rules based on service names, full match syntax with include lists, and stack names with glob patterns.

```yaml
swarm:
  rules:
    - service_name: nginx
      keywords:
        - error
        - regex: \timeout\b.*

    # you can also use the full match syntax
    - match:
        include:
          service_names: ["redis"]
      keywords:
        - keyword: critical
        - attach_logfile: true

    # or select a whole stack and use glob patterns
    - stack_name: my_stack*
      keywords:
        - keyword: critical
        - regex: \timeout\b.*

```

--------------------------------

### v1 Docker Labels vs v2 Docker Labels

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Illustrates the renaming of Docker label keys for configuration in v2 compared to v1. Ensure to update your labels to match the new v2 key names.

```text
v1 label key | v2 label key
--|--
`loggifly.keywords.0.action` | `loggifly.keywords.0.container_action`
`loggifly.keywords.0.action_cooldown` | `loggifly.keywords.0.container_action_cooldown`
`loggifly.keywords.0.notification_cooldown` | `loggifly.keywords.0.trigger_cooldown`
`loggifly.keywords.0.hide_regex_in_title` | `loggifly.keywords.0.hide_full_regex`
`loggifly.keywords.0.excluded_keywords` | `loggifly.keywords.0.ignore_keywords`
`loggifly.keywords.0.keyword_group` | `loggifly.keywords.0.all_of`
```

--------------------------------

### Global Keywords Configuration

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/global.md

Illustrates how to define global keywords that are applied to every matched target across all sources in Loggifly.

```yaml
global:
  # --- Global keywords --------------------------------------------------
  # Applied to EVERY matched target across ALL sources (containers + swarm).
  # Combined with source-level keywords and rule-level keywords.
  keywords:
    - keyword: "critical"
    - keyword: "out of memory"


```

--------------------------------

### Minimal LoggiFly Configuration File

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

A basic config.yaml file for LoggiFly. For a full list of options, refer to the Configuration Walkthrough.

```yaml
<<< @/configs/minimal_config.yaml{yaml}
```

--------------------------------

### Overriding Defaults at Rule Level

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

This example illustrates how to override global default settings at the rule level. The 'debug-rule' for 'my-app' sets a specific 'trigger_cooldown' of 10, which takes precedence over the global default of 0.

```yaml
defaults:
  trigger_cooldown: 0

containers:
  rules:
    - id: debug-rule
      container_name: my-app
      trigger_cooldown: 10 # overrides trigger_cooldown for containers matching this rule
      ntfy_topic: "my-app"
      ignore_keywords:
        - keyword: "debug"
      keywords:
        - keyword: "error"
```

--------------------------------

### Run Migration Script with Docker (Custom Paths)

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Execute the Loggifly v1 to v2 migration script using Docker, specifying custom input and output file paths within the container. This allows for more flexibility when your configuration files are not in the default location.

```bash
docker run --rm \
  -v /path/to/your/config/dir:/config \
  ghcr.io/clemcer/loggifly-migrate:v1-to-v2 \
  -i /config/my_config.yaml -o /config/my_configv2.yaml
```

--------------------------------

### Applying Source-Level Keywords and Container Events

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

Configures keywords and container events that are applied to every container matched by any rule. These are combined with global and rule-level settings.

```yaml
containers:
  keywords:
    - keyword: "critical"    # monitored on every matched container
    - keyword: "out of memory"

  container_events:
    - event: crash           # monitored on every matched container
    - event: oom
```

--------------------------------

### Run Docker Migration Script (Custom Paths)

Source: https://github.com/clemcer/loggifly/blob/main/scripts/README.md

Execute the migration script in Docker, specifying custom input and output file paths within the container.

```bash
docker run --rm \
  -v /path/to/your/config/dir:/config \
  clemcer/loggifly-migrate:v1-to-v2 \
  -i /config/my_config.yaml -o /config/my_configv2.yaml
```

--------------------------------

### Disable Strict Configuration Validation in LoggiFly

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

Set the STRICT_CONFIG environment variable to 'false' in your docker-compose file to disable strict validation of the config.yaml file. This will log warnings for invalid fields instead of refusing to start.

```yaml
environment:
  STRICT_CONFIG: "false"
```

--------------------------------

### Configure Simple OliveTin Action

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/actions.md

Configure a single OliveTin action by specifying the `olivetin_action_id` for a keyword or regex. Global or per-container settings for OliveTin URL, username, and password can be used.

```yaml
global:
  defaults:
    olivetin_url: http://192.168.178.20:1337
    olivetin_username: admin
    olivetin_password: password
    
containers:
  rules:
    - container_name: my-app
      keywords:
        - regex: 'download.*failed'
          olivetin_action_id: some-action-id
```

--------------------------------

### Configure Multiple OliveTin Actions with Arguments

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/actions.md

Configure multiple OliveTin actions and pass custom arguments to them using the `olivetin_actions` field. Each action can have its own set of arguments.

```yaml
containers:
  rules:
    - container_name: my-app
      keywords:
        - keyword: critical
          olivetin_actions:
            - id: some-action-id
              arguments:
                - name: arg1
                  value: value1
                - name: arg2
                  value: value2
            - id: some-other-action-id
              arguments:
                - name: arg3
                  value: value3
                - name: arg4
                  value: value4
```

--------------------------------

### Basic LoggiFly Settings

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/settings.md

Configure core LoggiFly behaviors such as log level, multi-line entry handling, config reloading, and notification preferences.

```yaml
settings:
  log_level: INFO
  multi_line_entries: true
  reload_config: true
  system_notifications: true
  compact_summary_message: false
```

--------------------------------

### Migrate Settings Structure from v1 to v2

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

In v2, inheritable settings like `title_template` move from `settings:` to `global.defaults:`. Application-only settings remain under `settings:`.

```yaml
# v1
settings:
  notification_cooldown: 10
  attach_logfile: true
  ntfy_priority: 4
  title_template: "[{container_name}] {keywords}"

# v2
global:
  defaults:
    trigger_cooldown: 10
    attach_logfile: true
    ntfy_priority: 4
    title_template: "[{{ container_name }}] {{ keywords }}"
```

--------------------------------

### Fluentbit Compose File for Systemd Monitoring

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/examples.md

A Docker Compose file to set up a fluentbit container for monitoring systemd journal logs. This configuration streams journal logs to fluentbit for LoggiFly to process.

```yaml
services:
  fluentbit:
    image: fluent/fluent-bit:latest
    container_name: fluentbit
    read_only: true
    volumes:
      - /var/log/journal:/var/log/journal:ro
    command: >
      /fluent-bit/bin/fluent-bit
      -i systemd -p tag=journal -p path=/var/log/journal -p read_from_tail=true
      -o stdout -p match=* -p format=json_lines
    restart: unless-stopped
```

--------------------------------

### List Docker Container Names

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/tips.md

Use this command to list the names of your running Docker containers. Ensure these names exactly match the container names configured in LoggiFly.

```sh
docker ps --format "{{.Names}}"
```

--------------------------------

### Run Docker Migration Script (Default Paths)

Source: https://github.com/clemcer/loggifly/blob/main/scripts/README.md

Use this command to run the migration script within a Docker container, using default input and output file paths.

```bash
docker run --rm \
  -v /path/to/your/config/dir:/config \
  clemcer/loggifly-migrate:v1-to-v2
```

--------------------------------

### Global Configuration Structure

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/global.md

Defines the basic structure for global settings and keywords within the Loggifly configuration.

```yaml
global:
  keywords:
    # ...
  defaults:
    # ...

```

--------------------------------

### Replace Deprecated Settings with Flexible Matching

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Deprecated settings like `monitor_all_containers` are replaced by flexible matching options within `containers.rules`, using `include` and `exclude` criteria.

```yaml
containers:
  rules:
    - match:
        include:
          container_names: ["*"]
        exclude:
          container_names: ["*-temp"]
      keywords:
        - keyword: error
```

--------------------------------

### Perform Actions on Monitored Container

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/actions.md

Configure container actions like restart or stop based on log keywords or container events. Set a cooldown period for actions.

```yaml
global:
  defaults:
    container_action_cooldown: 60  # 1 minute cooldown

containers:
  rules:
    - container_name: my-app
      keywords:
        # Act on log matches
        - regex: "process.*(failed|did not finish)" 
          container_action: restart  # Restart the container when this regex is found
        - keyword: critical
          container_action: stop     # Stop the container when this keyword is found
          container_action_cooldown: 10  # 10 seconds cooldown for this action

      container_events:
        # Act on container events
        - event: crash
          container_action: restart
          message_template: '{action_result_message}'
```

--------------------------------

### Basic Notifications Configuration

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/notifications.md

This snippet shows the basic structure for configuring ntfy, Apprise, and webhook notifications in the config.yaml file. You can set all three services simultaneously.

```yaml
notifications:
  ntfy: ...
  apprise: ...
  webhook: ...
```

--------------------------------

### Swarm Service Labels vs. Container Labels

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/label-config.md

Illustrates the difference in label application for Swarm services. Labels under 'deploy' are only read on manager nodes, while labels directly under the service are read on all nodes.

```yaml
services:
  webserver:
    image: nginx

    # With these labels LoggiFly would only monitor containers
    # of the nginx service that are running on manager nodes
    deploy:
      labels:
        loggifly.monitor: "true" 

    # With these labels LoggiFly would monitor all containers 
    # of the nginx service, both on manager and worker nodes
    labels:
      loggifly.monitor: "true"  

```

--------------------------------

### Simple and Keyword Types

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/keywords-and-triggers.md

Define simple keywords or specify keywords using the 'keyword:' prefix.

```yaml
keywords:
  - error           # simple keyword
  - keyword: failed login   # another way to set a simple keyword
```

--------------------------------

### v1 vs v2 Container Exclusion Configuration

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Shows the migration from `settings.excluded_containers` in v1 to `containers.never_monitor` in v2. Supports glob patterns in v2.

```yaml
# v1
settings:
  excluded_containers: ["loggifly", "socket-proxy"]

# v2
containers:
  never_monitor:
    container_names: ["loggifly", "socket-proxy"]
```

--------------------------------

### v1 vs v2 System Notification Settings

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Illustrates the consolidation of multiple disable flags into a single `system_notifications` field in v2. Allows for selective disabling.

```yaml
settings:
  log_level: INFO
  multi_line_entries: true
  reload_config: true
  system_notifications: true
```

```yaml
settings:
  system_notifications: false   # disable all system notifications

  # or selectively:
  system_notifications:
    start: true
    shutdown: true
    config_reload: false
    monitor_event: true
```

--------------------------------

### Docker Compose for Global Swarm Service Deployment

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/swarm.md

This Docker Compose file configures LoggiFly to run as a global service on every node in a Swarm cluster. It mounts the Docker socket, sets the time zone and LoggiFly mode, and specifies a Docker Config for its configuration file.

```yaml
version: "3.8"

services:
  loggifly:
    image: ghcr.io/clemcer/loggifly:latest
    deploy:
      mode: global  # runs on every node
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 5
    volumes: 
      - /var/run/docker.sock:/var/run/docker.sock:ro 
    environment:
      TZ: Europe/Berlin
      LOGGIFLY_MODE: swarm
      # You can use environment variables instead of a config.yaml if you want
      # SWARM_SERVICES: nginx,redis
      # SWARM_STACKS: my_stack1,my_stack2
      # GLOBAL_KEYWORDS: keyword1,keyword2
      # For more environment variables see the environment variables section in the docs 
# Comment out the rest of this file if you are only using environment variables
    configs:
      - source: loggifly-config
        target: /config/config.yaml  

configs:
  loggifly-config:
    file: ./config.yaml  # SET THE PATH TO YOUR CONFIG.YAML HERE

```

--------------------------------

### Docker Compose with 11notes/socket-proxy

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

This Docker Compose configuration utilizes the 11notes/socket-proxy to securely expose the Docker socket to LoggiFly.

```yaml
<<< @/compose/compose.11notes-proxy.yaml{yaml}
```

--------------------------------

### Rule Matching with Full `match` Block

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

Uses a comprehensive `match:` block to define inclusion and exclusion criteria for containers based on names. This offers flexible matching capabilities.

```yaml
containers:
  rules:
    # full match block with include and exclude lists
    - match:
        include:
          container_names: ["web-*", "api-*"]
        exclude:
          container_names: ["*-test"]
      keywords:
        - keyword: "error"
```

--------------------------------

### Update `swarm_services:` to `swarm:` Structure in v2

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

The `swarm_services:` key in v1 is renamed to `swarm:` in v2, and its structure now mirrors the `containers:` configuration with `rules` for matching.

```yaml
# v1
swarm_services:
  my-service:
    keywords:
      - keyword: timeout

# v2
swarm:
  rules:
    - match:
        include:
          service_names: ["my-service"]
        exclude:
          stack_names: ["*-temp"]
      keywords:
        - keyword: timeout

    # shorthand for match.include.service_names: ["my-service"]
    - service_name: my-service
      keywords:
        - keyword: timeout
```

--------------------------------

### Regex Keyword Types

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/keywords-and-triggers.md

Use regular expressions to match log entries. Named capture groups can extract values for templates.

```yaml
keywords:
  - regex: 'download.*failed'
  - regex: 'process (?P<pid>\d+) crashed'  # named capture group → available in templates
```

--------------------------------

### Rule Matching with Shorthand Syntax

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

Employs a simplified `container_name:` shorthand for rules that match based on a single container name. This is equivalent to a basic `match:` block.

```yaml
containers:
  rules:
    # shorthand syntax for simple cases
    - container_name: nginx   # shorthand
      keywords:
        - keyword: error
    
    # equivalent to:
    # - match:
    #     include:
    #       container_names: ["nginx"]
    #   keywords:
    #     - keyword: error
```

--------------------------------

### Docker Compose with Direct Docker Socket Access

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/getting-started.md

This Docker Compose configuration allows LoggiFly direct access to the Docker socket. Use this if you need features like container actions.

```yaml
<<< @/compose/compose.yaml{yaml}
```

--------------------------------

### Threshold-Based Triggering for Keywords

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/keywords-and-triggers.md

Configure a keyword to trigger only after it appears a specified number of times within a given timeframe. This helps reduce noise from infrequent matches.

```yaml
keywords:
  - keyword: "connection timeout"
    trigger_on:
      count: 5
      timeframe: 60
    title_template: "{{ container_name }}: {{ trigger_on_count }} timeouts in {{ trigger_on_timeframe }}s"
```

--------------------------------

### Configure Multiple Remote Docker Hosts with TLS and Labels

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/remote-hosts.md

Set up LoggiFly to connect to a local Docker socket and two remote TLS-enabled Docker hosts. The remote host '192.168.178.81' is labeled 'foobar', while the other remote host and the local socket are identified by their hostnames. Certificate structure for TLS is also shown.

```yaml
version: "3.8"
services:
  loggifly:
    image: ghcr.io/clemcer/loggifly:latest
    container_name: loggifly 
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./loggifly/config:/config # Place your config.yaml here if you are using one
      - ./certs:/certs
      # Assuming the Docker hosts use TLS, the folder structure for the certificates should be like this:
      # /certs/
      # ├── 192.168.178.80/
      # │   ├── ca.pem
      # │   ├── cert.pem
      # │   └── key.pem
      # └── 192.168.178.81/
      #     ├── ca.pem
      #     ├── cert.pem
      #     └── key.pem
    environment:
      TZ: Europe/Berlin
      DOCKER_HOST: tcp://192.168.178.80:2376,tcp://192.168.178.81:2376|foobar
    restart: unless-stopped
```

--------------------------------

### Perform Actions on Other Containers

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/actions.md

Configure actions to be performed on different containers by specifying the target container name after the action, separated by '@'.

```yaml
containers:
  rules:
    - container_name: my-app
      keywords:
        - regex: "process.*(failed|did not finish)" 
          container_action: restart@some-other-container  # Restart another container when this regex is found
        - keyword: critical
          container_action: stop@some-other-container     # Stop another container when this keyword is found
        - keyword: timeout
          container_action: start@some-other-container
```

--------------------------------

### Containers Configuration Structure

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/config/containers-and-rules.md

Defines the overall structure of the `containers:` configuration section, including scope, exclusion lists, defaults, keywords, events, and rules.

```yaml
containers:
  scope: ...          # optional: restrict this entire block to specific hosts
  never_monitor: ...  # absolute exclusion list
  defaults: ...       # overrides global defaults: for all container targets
  keywords: [...]     # applied to every matched container
  container_events: [...] # applied to every matched container
  rules: [...]        # determine which containers to monitor
  groups: [...]       # advanced: groups of rules sharing common config
```

--------------------------------

### Enable Global merge_matches in v2

Source: https://github.com/clemcer/loggifly/blob/main/docs/guide/migrate-to-v2.md

Restore the v1 behavior where multiple keyword matches from a single log line are merged into one notification. Apply this setting globally in your v2 configuration.

```yaml
global:
  defaults:
    merge_matches: true
```