Logmojo Documentation

Complete guide to installing, configuring, and using Logmojo for high-performance log management.

Getting Started

System Requirements

Minimum Requirements

• OS: Linux, macOS, Windows (x86_64 or ARM64)
• RAM: 512MB
• Disk: 100MB free space
• Dependencies: grep, zgrep (for log search)

Recommended

• RAM: 1GB+
• Disk: 1GB+ (for log storage)
• Network: 1Gbps+ for high log volume

Development Prerequisites

For development setup, you need:

• Go: 1.24+ installed
• Git: For cloning the repository
• Air: For live reload (optional but recommended)

Installation

Option 1: Automated Installation (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/saiarlen/logmojo/main/scripts/deploy.sh | sudo bash

This automated script will:

• Auto-detect your OS and architecture
• Download the latest binary and assets
• Create a systemd service
• Configure firewall rules
• Start the service automatically

Option 2: Manual Installation (All Platforms)

Step 1: Download Binary

# Linux x86_64
wget https://github.com/saiarlen/logmojo/releases/latest/download/logmojo-linux-amd64

# Linux ARM
wget https://github.com/saiarlen/logmojo/releases/latest/download/logmojo-darwin-arm64

# macOS ARM64 (M1/M2)
wget https://github.com/saiarlen/logmojo/releases/latest/download/logmojo-darwin-arm64

# macOS x86_64 (Intel)
wget https://github.com/saiarlen/logmojo/releases/latest/download/logmojo-darwin-amd64

Step 2: Download Required Files

# Clone repository for assets
git clone https://github.com/saiarlen/logmojo.git
cd logmojo

# Move binary into folder
mv ../logmojo-* ../logmojo

# Copy environment file and setup
cp .env.example .env

Step 3: Make Executable and Run

# Make executable
chmod +x logmojo-linux-amd64

# Run
./logmojo-linux-amd64

Step 4: Use systemd or supervisor to the app in background

# Use Logmojo.service file for systemd reference

Option 3: Windows x64 Installation

Step 1: Download Windows Binary

Download the latest Windows binary from GitHub Releases:

• logmojo-windows-amd64.exe (64-bit)

Step 2: Download Assets

Download the source code ZIP from the same release page and extract:

• views/ folder (HTML templates)
• public/ folder (CSS/JS assets)
• .env.example file
• config.yaml file

Step 3: Setup Configuration

# Copy environment file
copy .env.example .env

# Edit .env file with your settings

Step 4: Run Logmojo

# Run directly
logmojo-windows-amd64.exe

# Or create a Windows service using NSSM
nssm install logmojo "C:\path\to\logmojo-windows-amd64.exe"
nssm start logmojo

Windows Firewall Setup

netsh advfirewall firewall add rule name="Logmojo" dir=in action=allow protocol=TCP localport=7005

Option 4: Development Setup

Prerequisites: Go 1.24+, Git

# 1. Clone repository
git clone https://github.com/saiarlen/logmojo.git
cd logmojo

# 2. Install dependencies
go mod download

# 3. Setup environment
cp .env.example .env

# 4. Run with live reload (recommended)
go install github.com/cosmtrek/air@latest
air

# Or run normally
go run main.go

Development workflow:

# Pull latest changes
git pull origin main

# Update dependencies
go mod tidy

# Run tests
go test ./...

# Build binary
go build -o logmojo .

First Login

1. Access the web interface at http://localhost:7005
2. Login with default credentials: admin / admin
3. ⚠️ Change password immediately via Settings page

Configure Log Sources

Edit config.yaml to add your applications:

apps:
  - name: "My Application"
    service_name: "my-app"
    logs:
      - name: "Application Log"
        path: "/var/log/myapp/app.log"
      - name: "Error Log"
        path: "/var/log/myapp/error.log"

Restart the service to apply changes:

sudo systemctl restart logmojo

Updates

Zero-Downtime Update (Linux/macOS)

Automated update script that preserves your data and configuration:

curl -fsSL https://raw.githubusercontent.com/saiarlen/logmojo/main/scripts/update.sh | sudo bash

This update script will:

• Download the latest binary
• Preserve your existing configuration and data
• Restart the service with zero downtime
• Maintain all user accounts and settings

Manual Update (Windows/Linux/macOS)

For Linux/macOS:

1. Backup Current Installation:

   # Backup your current .env and config files
   cp .env .env.backup
   cp config.yaml config.yaml.backup
   
   # Backup database (optional)
   cp monitor.db monitor.db.backup

2. Download Latest Release: Get the latest binary and source code from GitHub Releases
3. Stop Logmojo Service:

   # Stop systemd service
   sudo systemctl stop logmojo
   
   # Or stop the process manually
   pkill logmojo

4. Update Files:
   • Replace binary with new version (e.g., logmojo-linux-amd64)
   • Update views/ folder with new templates
   • Update public/ folder with new CSS/JS assets
   • Keep your existing .env and config.yaml files
5. Set Permissions:

   chmod +x logmojo-linux-amd64

6. Database Migration: The application will automatically update the database schema on startup if needed
7. Restart Service:

   # Start systemd service
   sudo systemctl start logmojo
   
   # Or run directly
   ./logmojo-linux-amd64

For Windows:

1. Backup Current Installation:

   # Backup your current .env and config files
   copy .env .env.backup
   copy config.yaml config.yaml.backup
   
   # Backup database (optional)
   copy monitor.db monitor.db.backup

2. Download Latest Release: Get the latest binary and source code ZIP from GitHub Releases
3. Stop Logmojo Service:

   # If using NSSM
   nssm stop logmojo
   
   # Or stop the process manually

4. Update Files:
   • Replace logmojo-windows-amd64.exe with the new binary
   • Update views/ folder with new templates
   • Update public/ folder with new CSS/JS assets
   • Keep your existing .env and config.yaml files
5. Database Migration: The application will automatically update the database schema on startup if needed
6. Restart Service:

   # If using NSSM
   nssm start logmojo
   
   # Or run directly
   logmojo-windows-amd64.exe

Features

Log Management

• Direct File Search: Uses grep/zgrep for instant searching without database ingestion
• Multi-format Support: Handles compressed files (.gz, .bz2, .xz, .lz4) automatically
• Smart Timestamp Parsing: Supports multiple log formats (ISO 8601, syslog, Unix timestamps)
• Real-time Streaming: Live log tailing with WebSocket connections

System Monitoring

• Real-time Metrics: CPU, RAM, Disk, and Network usage
• Historical Data: SQLite storage for 24-hour metric history
• Process Management: View and manage running processes
• Service Control: Complete systemd service management

Alert System

• Multi-type Rules: System metrics, log patterns, exception detection
• Smart Duplicate Prevention: Hash-based tracking prevents spam
• Email Notifications: HTML-formatted alerts with severity levels
• Webhook Support: Slack, Discord, and custom webhook integration

Configuration

Environment Variables

Key configuration options in .env:

# Server Configuration
MONITOR_GENERAL_VERSION="dev"
MONITOR_SERVER_LISTEN_ADDR=0.0.0.0:7005
MONITOR_DATABASE_PATH=./monitor.db

# Security
MONITOR_SECURITY_JWT_SECRET=your-secret-key-change-this


# Email Notifications
MONITOR_NOTIFIERS_EMAIL_ENABLED=true
MONITOR_NOTIFIERS_EMAIL_SMTP_HOST=smtp.gmail.com
MONITOR_NOTIFIERS_EMAIL_SMTP_PORT=587
MONITOR_NOTIFIERS_EMAIL_USERNAME=your-email@gmail.com
MONITOR_NOTIFIERS_EMAIL_PASSWORD=your-app-password
MONITOR_NOTIFIERS_EMAIL_FROM=alerts@company.com
MONITOR_NOTIFIERS_EMAIL_TO=admin@company.com

# Webhook Notifications
MONITOR_NOTIFIERS_WEBHOOK_ENABLED=false
MONITOR_NOTIFIERS_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK

User Management

Manage users via command line:

# Create user
./logmojo --user=create --username=john --password=SecurePass123

# List users
./logmojo --user=list

# Update password
./logmojo --user=update --username=john --password=NewPass456

# Delete user
./logmojo --user=delete --username=john

Service Management

# Start service
sudo systemctl start logmojo

# Stop service
sudo systemctl stop logmojo

# Restart service
sudo systemctl restart logmojo

# Check status
sudo systemctl status logmojo

# View logs
sudo journalctl -u logmojo -f

API Reference

Authentication

All API endpoints (except login) require JWT authentication via HTTP-only cookies.

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin"
}

Log Management

GET /api/logs/search?q=error&app=MyApp&log=ErrorLog&limit=100

Response:
[
  {
    "app": "MyApp",
    "file": "/var/log/error.log",
    "level": "ERROR",
    "message": "Database connection failed",
    "timestamp": "2025-01-12T12:00:00Z"
  }
]

System Metrics

GET /api/metrics/host

Response:
{
  "cpu_percent": 45.2,
  "ram_percent": 67.8,
  "ram_total": 8589934592,
  "ram_used": 5825830912,
  "disk_percent": 42.1,
  "disk_total": 1000204886016,
  "disk_used": 421186068480,
  "uptime": 86400,
  "load_avg": 1.25
}

Alert Management

POST /api/alerts/rules
Content-Type: application/json

{
  "name": "High CPU Alert",
  "type": "system_metric",
  "condition": "cpu_high",
  "threshold": 80.0,
  "severity": "high",
  "enabled": true,
  "email_enabled": true
}

WebSocket Endpoints

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:7005/api/ws/metrics');

ws.onmessage = (event) => {
  const metrics = JSON.parse(event.data);
  console.log(metrics);
};

// Connect to WebSocket for live logs
const ws = new WebSocket('ws://localhost:7005/api/ws/logs?app=MyApp&log=ErrorLog');

ws.onmessage = (event) => {
  const logLine = event.data;
  console.log(logLine);
};

Troubleshooting

Common Issues

"No Logs Found"

• Check file permissions: ls -la /var/log/myapp/
• Verify paths in config.yaml
• Ensure log files exist and are readable

Search Not Working

• Ensure grep/zgrep tools are installed: which grep zgrep
• Check $PATH environment variable
• Test grep manually: grep "error" /var/log/myapp/app.log

Service Won't Start

• Check logs: sudo journalctl -u logmojo -f
• Verify port 7005 is available: sudo lsof -i :7005
• Check permissions: ls -la /opt/logmojo

Port 7005 Already in Use

# Change port in .env
MONITOR_SERVER_LISTEN_ADDR=0.0.0.0:8080

# Restart service
sudo systemctl restart logmojo

Email Alerts Not Working

• Verify SMTP settings in .env
• For Gmail, use App Password (not regular password)
• Test with built-in alert test function
• Check logs for SMTP errors

Performance Optimization

• File Limits: Maximum 15 files per search, fallback to 3 most recent
• Search Timeout: 10-second timeout for better UX
• Result Limits: 2000 lines maximum per search
• Memory Management: Streaming output prevents OOM issues

Database Notes

• monitor.db stores only metadata (metrics, alerts, users)
• Logs are never stored in database (performance feature)
• Safe to delete monitor.db to reset (will lose metrics history)
• Database is automatically created on first run