LoggiFly

Report Bug Request Feature

LoggiFly - A Lightweight Tool to monitor Docker Logs and send Notifications.
Never miss critical container events again - Get instant alerts for security breaches, system errors, or custom patterns through your favorite notification channels. 🚀

Ideal For:

• ✅ Catching security breaches (e.g., failed logins in Vaultwarden)
• ✅ Debugging crashes with attached log context
• ✅ Monitoring custom app behaviors (e.g., when a user downloads an audiobook on your Audiobookshelf server)

---

Content

• Features
• Screenshots
• Quick Start
• Configuration Deep Dive
  • Basic config structure
  • Environment Variables
• Tips

---

🚀 Features

• 🔍 Plain Text, Regex & Multi-Line Log Detection: Catch simple keywords or complex patterns in log entries that span multiple lines.
• 🚨 Ntfy/Apprise Alerts: Send notifications directly to Ntfy or via Apprise to 100+ different services (Slack, Discord, Telegram).
• 🐳 Fine-Grained Control: Unique keywords and other settings (like ntfy topic/tags/priority) per container.
• 📁 Log Attachments: Automatically include a log file to the notification for context.
• ⚡ Auto-Restart on Config Change: The program restarts when it detects that the config file has been changed.

---

🖼 Screenshots

---

⚡️ Quick start

In this quickstart only the most essential settigs are covered, here is a more detailed config walkthrough.

Choose your preferred setup method - simple environment variables for basic use, or a YAML config for advanced control.

• Environment variables allow for a simple setup and let you spin this thing up in a minute
• With YAML you can use complex Regex patterns and have different keywords & other settings per container.

Click to expand: 🐋 Basic Setup: Docker Compose (Environment Variables)

Ideal for quick setup with minimal configuration

version: "3.8"
services:
  loggifly:
    image: ghcr.io/clemcer/loggifly:latest
    container_name: loggifly
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      # Choose at least one notification service
      NTFY_URL: "https://ntfy.sh"       # or your self-hosted instance
      NTFY_TOPIC: "your_topic"          # e.g., "docker_alerts"
      APPRISE_URL: "discord://..."      # Apprise-compatible URL
    
      CONTAINERS: "vaultwarden,audiobookshelf"  # Comma-separated list
      GLOBAL_KEYWORDS: "error,failed"           # Basic keyword monitoring
      GLOBAL_KEYWORDS_WITH_ATTACHMENT: "critical" # Attaches a log file to the notification

Click to expand: 📜 Advanced Setup: YAML Configuration

Recommended for granular control and regex patterns.
This config only covers the essential settings, you can find a full config walkthrough here or just take a look at this example config.

1. Insert the following line in the volumes section of the docker compose from Option 1:

volumes:
  - ./config.yaml:/app/config.yaml  # Path to your config file

2. Configure the config.yaml.

# You have to configure at least one container.
containers:
  container-name:  # Exact container name
  # You don't have to use both `keywords` and `keyword_with_attachment`. One is enough
    keywords:
      - error
      - regex: (username|password).*incorrect  # Use regex patterns when you need them
    # Attach a log file to the notification 
    keywords_with_attachment:
      - warn

# Optional. These keywords are being monitored for all configured containers
global_keywords:
  keywords:
    - failed
  keywords_with_attachment:
    - critical

notifications:     
  # Configure either Ntfy or Apprise or both
  ntfy:
    url: http://your-ntfy-server  
    topic: loggifly                   
    token: ntfy-token               # In case you need authentication
  apprise:
    url: "discord://webhook-url"    # Any Apprise-compatible URL (https://github.com/caronc/apprise/wiki)

When everything is configured start the container

docker compose up -d

---

🤿 Configuration Deep Dive

The Quick Start only covered the essential settings, here is a more detailed walktrough of the configuration options.

📁 Basic Structure

The config.yaml file is divided into four main sections:

1. settings: Global settings like cooldowns and log levels. (Optional since they all have default values)
2. notifications: Configure Ntfy (URL, Topic, Token, Priority and Tags) and/or your Apprise URL
3. containers: Define which Containers to monitor and their specific Keywords (plus optional settings).
4. global_keywords: Keywords that apply to all monitored Containers.

Click to expand: ⚙️ Settings

# These are the default settings
settings:          
  log_level: INFO               # DEBUG, INFO, WARNING, ERROR
  notification_cooldown: 5      # Seconds between alerts for same keyword (per container)
  attachment_lines: 20          # Number of Lines to include in log attachments
  multi_line_entries: true      # Monitor and catch multi-line log entries instead of going line by line. 
  disable_restart: false        # Disable restart when a config change is detected 
  disable_start_message: false  # Suppress startup notification
  disable_shutdown_message: false  # Suppress shutdown notification
  disable_restart_message: false   # Suppress config reload notification

Click to expand: 📭 notifications

notifications:                       
  # At least one of the two (Ntfy/Apprise) is required.
  ntfy:
    url: http://your-ntfy-server    # Required. The URL of your Ntfy instance
    topic: loggifly.                # Required. the topic for Ntfy
    token: ntfy-token               # In case you need authentication 
    priority: 3                     # Ntfy priority (1-5)
    tags: kite,mag                  # Ntfy tags/emojis 
  apprise:
    url: "discord://webhook-url"    # Any Apprise-compatible URL (https://github.com/caronc/apprise/wiki)

Click to expand: 🐳 containers

containers:
  container-name:               # Must match exact container_name
    # The next 5 settings are optional
    # They override the respective global setting for this container 
    ntfy_topic: your_topic
    ntfy_tags: "tag1, tag2"     
    ntfy_priority: 4            
    attachment_lines: 10        
    notification_cooldown: 10   

  # You don't have to use both `keywords` and `keyword_with_attachment`. One is enough. 
    keywords:                                 
      - error                                  # Simple text matches
      - regex: (username|password).*incorrect  # Use regex patterns when you need them
    # When one of these keywords is found a logfile is attached to the notification
    keywords_with_attachment:
      - critical

# If you have configured global_keywords and don't need container specific settings
# you can leave the container config blank.
  another-containers-name:

Click to expand: 🌍 global_keywords

# This section is optional.
# These keywords are being monitored for all containers. 
global_keywords:              
  keywords:
    - error
  # When one of these keywords is found a logfile is attached
  keywords_with_attachment:
    - regex: (critical|error)

Here you can find a full example config.

🍀 Enviroment Variables

Except for container specific settings and regex patterns you can configure most settings via docker environment variables.

Click to expand: Enviroment Variables

Variables	Description	Default
NTFY_URL	URL of your Ntfy server instance	N/A
NTFY_TOKEN	Authentication token for Ntfy in case you need authentication.	N/A
NTFY_TOPIC	Notification topic for Ntfy.	N/A
NTFY_TAGS	Ntfy Tags/Emojis for ntfy notifications.	kite,mag
NTFY_PRIORITY	Notification priority for ntfy messages.	3 / default
APPRISE_URL	Any Apprise-compatible URL	N/A
CONTAINERS	A comma separated list of containers to use with global keywords. These are added to the containers from the config.	N/A
GLOBAL_KEYWORDS	Keywords that will be monitored for all containers. Overrides global_keywords.keywords from the config.yaml.	N/A
GLOBAL_KEYWORDS_WITH_ATTACHMENT	Notifications triggered by these global keywords have a logfile attached. Overrides global_keywords.keywords_with_attachment from the config.yaml.	N/A
NOTIFICATION_COOLDOWN	Cooldown period (in seconds) per container per keyword before a new message can be sent	5
LOG_LEVEL	Log Level for LoggiFly container logs.	INFO
MULTI_LINE_ENTRIES	When enabled the program tries to catch entries that span multiple log lines. If you encounter bugs or you simply don't need it you can disable it.	True
ATTACHMENT_LINES	Define the number of Log Lines in the attachment file	20
DISABLE_RESTART	Disable automatic restarts when the config file is changed.	False
DISBLE_START_MESSAGE	Disable startup message.	False
DISBLE_SHUTDOWN_MESSAGE	Disable shutdown message.	False
DISABLE_RESTART_MESSAGE	Disable message on config change when program restarts.	False

---

💡 Tips

1. If you want to Protect Sensitive Credentials like tokens or Apprise URLs, store them in environment variables (not in YAML).
2. Ensure containers names exactly match your Docker container names.
   • Find out your containers names: docker ps --format "{{.Names}}"
   • 💡 Pro Tip: Define the container_name: in your compose files.
3. Troubleshooting Multi-Line Logs. If multi-line entries aren't detected:
   • Wait for Patterns: LoggiFly needs a few lines to detect the pattern the log entries start with (e.g. timestamps/log formats)
   • Unrecognized Patterns: If issues persist, open an issue and share the affected log samples
4. Test Regex Patterns: Validate patterns at regex101.com before adding them to your config.

---

License

MIT