IRC Log to HTML Viewer

A real-time IRC log viewer that automatically converts IRC chat logs into styled HTML pages suitable for serving with nginx.

Features

• Real-time updates: Automatically regenerates HTML when log files are updated
• Jinja2 templating: Easy to customize HTML layout
• Clean styling: Dark theme IRC log viewer with syntax highlighting
• Systemd integration: Runs as a background service
• Debouncing: Intelligent file change detection to avoid excessive regeneration
• User mode colors: Different colors for ops, voice, admins, etc.

Directory Structure

/home/user/Git/Personal/IRCLogs/
├── irclogparser/             # Python module
│   ├── parser.py
│   ├── formatter.py
│   ├── generator.py
│   └── cli.py
├── install/                  # Installation files
│   ├── scripts/
│   │   ├── irc-log-parser    # HTML generator script
│   │   ├── irc-log-watcher   # File watcher daemon
│   │   └── generate-index    # Index page generator
│   └── irc-log-watcher.service  # systemd service file
├── templates/
│   └── log.html.j2           # Jinja2 HTML template
├── static/
│   └── style.css             # CSS styling
├── config.yaml               # Configuration file
├── pyproject.toml            # Package configuration
├── requirements.txt          # Python dependencies
├── logs/                     # Symlink this to your bouncer logs
│   └── #channel.log
└── html/                     # Generated HTML (nginx serves from here)
    ├── style.css
    └── #channel.html

Installation

1. Install Package

Install the package and scripts using uv (recommended) or pip:

Using uv (recommended):

# Install as a tool with isolated environment (makes scripts globally available)
uv tool install .

# Or install in a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install .

Using pipx (alternative for isolated install):

pipx install .

Using pip:

# Install in user mode (recommended)
pip3 install --user .

# Or create and use a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip3 install .

# Or in development/editable mode
pip3 install --user -e .

This will install:

• The irclogparser Python module
• All required dependencies
• Scripts to your PATH: irc-log-parser, irc-log-watcher, generate-index

Note: If using uv tool install or pipx, the scripts will be available globally. If using a virtual environment, you'll need to activate it to use the scripts, or use the full path (e.g., .venv/bin/irc-log-watcher).

3. Configure Log Directory

Create a symlink from your bouncer's log directory to the logs directory:

ln -s /path/to/your/bouncer/logs logs

Alternatively, edit config.yaml to point to your log directory directly.

4. Test the Parser

Test with the sample log to ensure everything works:

# If installed with pip/uv:
irc-log-parser samplelogs/#r_a_dio.log html/#r_a_dio.html

# If running standalone scripts from project directory:
./install/scripts/irc-log-parser samplelogs/#r_a_dio.log html/#r_a_dio.html

Check the generated HTML:

ls -lh html/

5. Set Up systemd Service (Optional but Recommended)

Copy the service file to systemd:

sudo cp install/irc-log-watcher.service /etc/systemd/system/

Edit the service file to match your setup:

sudo nano /etc/systemd/system/irc-log-watcher.service

Update the User, Group, and WorkingDirectory paths if needed.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable irc-log-watcher.service
sudo systemctl start irc-log-watcher.service

Check the service status:

sudo systemctl status irc-log-watcher.service

View logs:

sudo journalctl -u irc-log-watcher.service -f

Note: The systemd service file assumes the package is installed via pip/uv. The irc-log-watcher command should be in your PATH after installation.

6. Configure nginx

Add a server block to serve the HTML files:

server {
    listen 80;
    server_name irclogs.example.com;

    root /home/user/Git/Personal/IRCLogs/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
        autoindex on;  # Enable directory listing
    }

    location ~* \.(css|js)$ {
        expires 1d;
        add_header Cache-Control "public, immutable";
    }
}

Reload nginx:

sudo systemctl reload nginx

Usage

Manual Generation

Generate HTML for a single log file:

# If installed with pip/uv:
irc-log-parser logs/#channel.log html/#channel.html

# From project directory (standalone scripts):
./install/scripts/irc-log-parser logs/#channel.log html/#channel.html

Generate an index page listing all logs:

# If installed with pip/uv:
generate-index html

# From project directory (standalone scripts):
./install/scripts/generate-index html

Running the Watcher Manually

For testing or if you don't want to use systemd:

# If installed with pip/uv:
irc-log-watcher

# From project directory (standalone scripts):
./install/scripts/irc-log-watcher

Press Ctrl+C to stop.

Using the systemd Service

Start/stop/restart the service:

sudo systemctl start irc-log-watcher.service
sudo systemctl stop irc-log-watcher.service
sudo systemctl restart irc-log-watcher.service

Configuration

Edit config.yaml to customize:

# Directory containing IRC log files
log_directory: logs

# Output directory for generated HTML files
html_directory: html

# Static files directory (CSS, JS, etc.)
static_directory: static

# Template directory
template_directory: templates

# File patterns to watch
log_patterns:
  - "*.log"
  - "#*.log"

# Debounce time in seconds
debounce_seconds: 2

# Copy static files to HTML directory
copy_static_files: true

# Generate an index.html listing all logs
generate_index: true

# Preserve IRC formatting (colors, bold, etc.) as HTML
preserve_formatting: true

# Maximum number of log entries to include in HTML (most recent entries)
# Set to 0 or null for unlimited
max_log_entries: 500

# Logging level
log_level: INFO

Customization

Modifying the HTML Template

Edit templates/log.html.j2 to change the HTML structure. The template receives:

• channel_name: Channel name from log filename
• log_entries: List of parsed log entries
• last_updated: Timestamp of generation

Modifying the CSS

Edit static/style.css to customize colors and styling.

Adding Features to the Parser

Edit irc_log_parser.py to add:

• IRC color code parsing
• URL linking
• Emoji support
• Custom formatting rules

Log Format

The parser expects logs in this format:

[2025-05-15T15:38:16.811Z] *** username joined
[2025-05-15T15:39:38.121Z] <@username> message text
[2025-05-15T15:44:21.683Z] <username> message text

Supported features:

• Timestamps in ISO 8601 format
• User modes: @ (op), & (admin), % (halfop), + (voice), ~ (owner)
• Join/quit/part messages
• Regular chat messages

Troubleshooting

Service won't start

Check logs:

sudo journalctl -u irc-log-watcher.service -n 50

Common issues:

• Missing Python dependencies
• Incorrect paths in service file
• Permissions on log/html directories

HTML not updating

1. Check if service is running:

   sudo systemctl status irc-log-watcher.service

2. Check file permissions:

   ls -la logs/ html/

3. Manually test the parser:

   irc-log-parser logs/#channel.log html/#channel.html

nginx 404 errors

1. Check html directory exists and has files:

   ls -la html/

2. Check nginx has permission to read the directory:

   sudo -u www-data ls /home/user/Git/Personal/IRCLogs/html/

License

Free to use and modify.