Finally a Handy Nginx Log Analyzer: Introducing NginxPulse

01 What Is NginxPulse?

Lightweight Nginx log analysis dashboard providing real‑time PV/UV statistics, IP geolocation (domestic via ip2region, overseas via ip‑api), client/browser parsing, multi‑site support, and customizable log formats. It fills the gap between heavyweight ELK stacks and minimalist CLI tools such as GoAccess.

02 Technology Stack

Backend: Go + Gin. Frontend: Vue3 + Vite + PrimeVue. Database: SQLite (single file). IP lookup flow: in‑memory cache → remote API batch request → local ip2region fallback, balancing speed and accuracy.

03 How to Run

Docker – One‑Liner

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -p 8089:8089 \
  -e WEBSITES='[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]' \
  -v /your/nginx/logs/access.log:/share/log/nginx/access.log:ro \
  -v $(pwd)/var/nginxpulse_data:/app/var/nginxpulse_data \
  magiccoders/nginxpulse:latest

Replace /your/nginx/logs/access.log with the actual Nginx access‑log path.

Docker Compose

version: "3.8"
services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    environment:
      WEBSITES: '[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]'
    volumes:
      - ./nginx_logs/access.log:/share/log/nginx/access.log:ro
      - ./var/nginxpulse_data:/app/var/nginxpulse_data
    restart: unless-stopped

Frontend UI: http://localhost:8088 Backend API: http://localhost:8089.

Multi‑Site Configuration

WEBSITES='[
  {"name":"主站","logPath":"/logs/main.log","domains":["www.example.com"]},
  {"name":"博客","logPath":"/logs/blog.log","domains":["blog.example.com"]}
]'

Log paths may use glob patterns such as "/logs/access-*.log"; compressed .gz files are parsed directly.

04 Useful Features

Remote Log Retrieval – Supports SFTP, HTTP, and S3/OSS. Example SFTP configuration:

{
  "id": "sftp-main",
  "type": "sftp",
  "host": "1.2.3.4",
  "port": 22,
  "user": "nginx",
  "auth": {"keyFile": "/secrets/id_rsa"},
  "path": "/var/log/nginx/access.log"
}

Push Agent – Lightweight agent can push logs from firewalled or edge nodes to the NginxPulse server in real time.

Custom Log Formats – Two definition methods:

Direct log_format syntax:

{
  "logFormat": "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent"
}

Regex with named capture groups:

{
  "logRegex": "^(?P<ip>\\S+) - (?P<user>\\S+) \[(?P<time>[^\\]]+)\]..."
}

Caddy Support – Set logType: "caddy" to parse JSON logs from Caddy.

Access Control – Define secret keys, e.g. ACCESS_KEYS='["your-secret-key"]', and require the X-NginxPulse-Key header; the UI prompts for the key when needed.

05 Common Questions

Log details empty after startup – Usually a permission issue. Grant read/write permissions to log and data directories, e.g. chmod -R 777 /path/to/logs /path/to/nginxpulse_data.

PV/UV remain zero – Internal IPs are excluded by default. Set PV_EXCLUDE_IPS='[]' to include them.

06 Single‑Binary Deployment

Build a self‑contained executable (amd64 or arm64) with: ./scripts/build_single.sh The generated binary embeds the frontend and serves both UI and API.

07 Final Notes

GitHub repository: https://github.com/likaia/nginxpulse Online demo: https://nginx-pulse.kaisir.cn/ MIT‑licensed project with over 2.6k stars.