Deploy NginxPulse for Real‑Time Nginx Log Analytics in Minutes

Overview

NginxPulse is a lightweight real‑time Nginx access‑log analysis dashboard. It provides PV/UV statistics, IP geolocation (ip2region for domestic IPs, ip‑api for foreign), client/browser parsing, multi‑site support and custom log format handling.

Technology Stack

Backend: Go + Gin. Frontend: Vue 3 + Vite + PrimeVue. Data store: SQLite.

Running with Docker

Single‑command container:

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/nginx/access.log:ro \
  -v $(pwd)/var/nginxpulse_data:/app/var/nginxpulse_data \
  magiccoders/nginxpulse:latest

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

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

After start, the UI is available at http://localhost:8088 and the API at http://localhost:8089.

Multi‑Site Configuration

Provide an array of site objects to the WEBSITES environment variable, for example:

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

Wildcard log paths (e.g., /logs/access-*.log) and compressed .gz files are supported.

Key Features

Remote log fetching via SFTP, HTTP, or S3/OSS.

Push Agent for edge or intranet servers to actively send logs.

Custom log format: either a log_format string or a named‑group regex.

Caddy support – set logType: "caddy" to parse JSON logs.

Access control – define ACCESS_KEYS=['your-secret-key'] and send the key in the X-NginxPulse-Key request header.

Common Issues

Empty log details : Usually a permission problem. Grant read/write permissions, e.g. chmod -R 777 /path/to/logs /path/to/nginxpulse_data.

PV/UV shows 0 : Internal IPs are excluded by default. Set PV_EXCLUDE_IPS='[]' to include them.

Single‑Binary Deployment

If Docker is not desired, build a self‑contained binary:

./scripts/build_single.sh

The resulting executable includes the built‑in frontend and runs on both amd64 and arm64.

Resources

GitHub repository: https://github.com/likaia/nginxpulse

Online demo: https://nginx-pulse.kaisir.cn/ (MIT licensed, ~1.4k stars).