hbenali/frontail repository overview

⁠frontail — streaming logs to the browser

frontail is a Node.js application that streams log files to the browser — tail -F with a UI. Point it at any file (or stdin) and watch lines appear in real time.

👉 Try the live demo⁠ — fake logs streaming continuously across every format frontail auto-colorizes, including Apache2/Nginx, Tomcat, Log4j/Logback, syslog, and ANSI-colored sources.

⁠Quick start

⁠npm

npm i -g @hbenali/frontail
frontail /var/log/syslog
# open http://127.0.0.1:9001

⁠Docker

docker run -d -p 9001:9001 -v /var/log:/log hbenali/frontail /log/syslog

⁠What's new

⁠Features

• Real-time log streaming over WebSocket

• Docker/Podman container log streaming — --container flag, any engine

• Source selector — sidebar pills to filter logs by source

• Container log download — download full container history via browser

• Log rotation support on Linux/macOS

• Auto-scroll with scroll-to-bottom FAB and +N new-line counter

• Pause/resume stream with skip counter

• Unread-line count in browser favicon

• Three built-in themes: Dark, Light, and Solarized

• Persistent UI settings across sessions

• Advanced filtering:

  • Plain text
  • Regular expressions
  • Case-sensitive matching
  • Inverted matching

• Keyword highlighting with up to 5 configurable keywords

• ANSI colour code rendering

• Automatic log colorizing for common log formats

• JSON log line colorizing for structured logs

• ANSI-source indicator showing whether a source already contains ANSI colours

• Sanitized downloads with ANSI escape sequences removed

• Level quick-filter chips for Error, Warn, Info, and Debug

• Saved filter presets

• Filtered downloads of exactly the currently visible lines

• Richer topbar showing the current source and filter state

• Update-available notification when the server is redeployed

• Click any line to select/deselect it

• Word-wrap toggle

• Per-line timestamps toggle

• Live statistics: total / visible / errors / warnings

• Tailing multiple files and stdin

• Basic authentication

• HTTPS support

• Running behind a path prefix

• Customizable log highlighting presets

• Customizable log colorization rules

⁠Installation

⁠npm

npm i -g @hbenali/frontail

⁠Docker

docker run -d \
  -p 9001:9001 \
  -v /var/log:/log \
  hbenali/frontail /log/syslog

⁠Standalone binaries

Standalone binaries are available for:

• Linux
• macOS
• Windows
• AMD64
• ARM64

⁠Usage

frontail [options] [file ...]

⁠Options

-V, --version                 output the version number
-h, --host <host>             listening host (default: 0.0.0.0)
-p, --port <port>             listening port (default: 9001)
-n, --number <number>         starting lines number (default: 10)
-l, --lines <lines>           lines stored in browser (default: 2000)
-t, --theme <theme>           name of the theme (default, dark)
-d, --daemonize               run as daemon
-U, --user <username>         Basic Auth username (requires -P)
-P, --password <password>     Basic Auth password (requires -U)
-k, --key <key.pem>           Private key for HTTPS (requires -c)
-c, --certificate <cert.pem>  Certificate for HTTPS (requires -k)
-C, --container <container>   container name or id
--container-engine <engine>   container engine (docker, podman)
                              (default: docker)
--pid-path <path>             daemon PID file
                              (default: /var/run/frontail.pid)
--log-path <path>             daemon log file
                              (default: /dev/null)
--url-path <path>             URL path for browser app (default: /)
--ui-hide-topbar              hide topbar
--ui-no-indent                don't indent log lines
--ui-highlight                enable word/line highlighting
--ui-highlight-preset <path>  custom highlight preset JSON
--ui-no-colors                disable log colorizing
--ui-colors-preset <path>     extra log colorizing rules JSON
--path <path>                 prefix path (default: /)
--disable-usage-stats         disable anonymous usage statistics
--help                        output usage information

Web interface:

http://[host]:[port]

⁠Keyboard shortcuts

⁠Filtering

Beyond the standard text filter, the sidebar provides additional filtering controls:

• Level chips — toggle Error, Warn, Info, and Debug lines on or off.
• Saved filters — save a filter together with its regex, case-sensitive, and invert settings.
• Filtered download — download exactly the lines currently visible after applying text filters, level filters, and source selection.

A small indicator next to the topbar title appears whenever a filter is actively narrowing the displayed logs.

⁠Mobile

On small screens, the sidebar becomes a full-screen overlay panel.

Tap the ☰ icon to open it and the ← button to return to the log view.

Logs automatically wrap to the available window width without horizontal scrolling.

⁠Tailing multiple files

Multiple files and shell glob patterns are supported.

Each file appears as a separate source in the sidebar.

frontail /var/log/nginx/access.log /var/log/nginx/error.log

frontail /var/log/*.log

⁠Mixing files and containers

Files and containers can be tailed simultaneously.

Each source appears separately in the sidebar.

frontail /var/log/syslog --container nginx -C postgres

⁠stdin

Use - to stream from standard input:

./server | frontail -

⁠Docker and Podman container logs

Stream logs from one or more containers:

frontail --container my-container

frontail -C c1 -C c2

Specify the container engine:

frontail \
  --container my-container \
  --container-engine podman

⁠Downloading container logs

Select a container source in the sidebar and press Download to retrieve its complete log history as a .log file.

⁠Docker setup for container streaming

To stream container logs from the frontail Docker image, mount the Docker socket:

services:
  frontail:
    image: hbenali/frontail:latest
    command: --container myapp /logs/syslog
    volumes:
      - /var/log:/logs:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

The container entrypoint automatically adds the frontail user to the Docker socket's group at startup.

⁠Highlighting presets

Enable log highlighting with:

frontail --ui-highlight /var/log/syslog

The default preset is:

./preset/default.json

Example:

{
  "words": {
    "err": "color: red;"
  },
  "lines": {
    "err": "font-weight: bold;"
  }
}

Available presets include:

• default
• npmlog
• python

⁠Log colorizing

Automatic log colorization is enabled by default.

Use:

frontail --ui-no-colors /var/log/syslog

to disable it server-wide.

Each viewer can also toggle Colors from the sidebar. This per-browser setting is persisted locally.

⁠ANSI-colored sources

When a line already contains ANSI escape codes, frontail renders those colours directly and skips format autodetection for that line.

The interface displays an indicator for ANSI-colored sources and provides a Sanitized download option that removes ANSI escape sequences.

⁠Plain-text sources

For regular text logs, frontail automatically recognizes and colorizes relevant fields such as:

• Timestamps
• IP addresses
• HTTP methods
• HTTP paths
• HTTP status codes
• Thread/PID information
• Log levels

Recognized formats include:

• JSON Lines
• Apache2 access logs
• Nginx access logs
• Apache2 error logs
• Nginx error logs
• Tomcat/Catalina logs
• Log4j/Logback pipe-delimited logs
• Generic syslog

If no known format matches, a generic fallback detects:

• Timestamps
• Log-level words
• IPv4 addresses
• Bracketed metadata
• Quoted strings

⁠JSON log colorizing

Structured JSON logs are rendered as readable, colorized key=value pairs instead of raw escaped JSON.

This works with formats such as:

• Pino
• Winston JSON
• Bunyan
• Go structured logging
• Other JSON-lines based logging systems

Fields such as level, time, status, and IP-related keys are automatically recognized where possible.

⁠Screenshots by format

The UI supports dedicated colorization for several common formats:

⁠Sanitized downloads

When ANSI codes are detected, the sidebar provides a Sanitized download button next to the normal download option.

The sanitized version removes ANSI escape sequences before downloading the log, making it convenient for:

• Copying logs into tickets
• Sharing logs with others
• Pasting logs into documentation
• Processing logs with other tools

⁠Custom log colorization rules

Custom rules can be supplied with:

frontail \
  --ui-colors-preset ./preset/my-colors.json \
  /var/log/syslog

Example:

{
  "name": "log4j-pipe",
  "regex": "^(\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}[.,]\\d{3})\\s*\\|\\s*(\\w+)\\s*\\|\\s*",
  "template": "{1:time} | {2:level} | "
}

⁠Rule properties

• regex — JavaScript regular-expression source.
• flags — optional regular-expression flags such as i.
• template — replacement template for matched text.

Capture groups can be styled using:

{1:time}
{1:ip}
{1:method}
{1:logger}
{1:status}
{1:level}

HTTP status codes are automatically colored according to their first digit.

Log levels are automatically styled according to severity.

Inline CSS colors are also supported:

{1:#c084fc}

⁠Running behind nginx

Example configuration:

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;

        location /frontail {
            proxy_pass http://127.0.0.1:9001/frontail;
            proxy_http_version 1.1;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }
}

Start frontail with:

frontail --url-path /frontail

The WebSocket upgrade headers are required for real-time log streaming.

⁠Docker

Published images are available from Docker Hub.

⁠Pull the latest image

docker pull hbenali/frontail:latest

⁠Build locally

docker build -t hbenali/frontail .

⁠Multi-architecture build

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg FRONTAIL_VERSION=$(node -p "require('./package.json').version") \
  --build-arg FRONTAIL_REVISION=$(git rev-parse HEAD) \
  -t hbenali/frontail:latest \
  --push .

⁠Run with file logs

docker run -d \
  -p 9001:9001 \
  -v /var/log:/log \
  hbenali/frontail /log/syslog

⁠Run with container streaming

docker run -d \
  -p 9001:9001 \
  -v /var/log:/log:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  hbenali/frontail /log/syslog \
  --container myapp

⁠Run with a custom colorization preset

docker run -d \
  -p 9001:9001 \
  -v /var/log:/log:ro \
  -v ./my-colors.json:/frontail/preset/my-colors.json:ro \
  hbenali/frontail /log/syslog \
  --ui-colors-preset /frontail/preset/my-colors.json

The Docker image uses:

• Multi-stage builds
• Node.js 24 LTS
• Debian Bookworm Slim
• Multi-architecture images
• Docker CLI for container streaming
• A dedicated non-root frontail user

⁠Development

The project includes deployment examples covering several configurations, including:

• Basic Docker Compose
• Multiple log sources
• Authentication
• Docker container streaming
• Podman container streaming
• nginx reverse proxy
• Kubernetes sidecar deployment

⁠Project information

Author: Houssem Ben Ali Website: https://frontail.hbenali.ovh/⁠ Contact: [email protected]⁠

⁠Credits

frontail is based on the original frontail project created by Maciej Winnicki.

This fork is maintained by Houssem Ben Ali.

⁠License

MIT