How nginxpulse Turns Nginx Logs into Insightful Dashboards

Overview

nginxpulse is a self‑hosted Nginx access‑log analysis panel written in Go (backend) and Vue 3 + TypeScript (frontend). It parses Nginx logs, stores metrics in PostgreSQL, and visualises them with interactive ECharts charts.

Key Features

PV/UV statistics : total page views, unique visitors, QPS and response‑time distribution. Internal IPs are excluded by default; clear PV_EXCLUDE_IPS to include them.

IP geolocation : local ip2region database with fallback to ip-api.com, results are cached.

Status‑code distribution : proportion of 2xx, 3xx, 4xx, 5xx responses.

Client parsing : identifies browsers, OS and device type.

Real‑time traffic view : live request stream useful during load testing or deployments.

Daily reports : per‑day aggregation with drill‑down to individual logs.

Technology Stack

Backend: Go with Gin framework and Logrus for logging. Since version 1.5.3 the database is PostgreSQL (bundled in the Docker image); earlier versions used SQLite. IP lookup combines ip2region (local) and ip-api.com (remote). Frontend: Vue 3, TypeScript and ECharts.

Deployment Options

1. Docker (single command)

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -v ./docker_local/logs:/share/logs:ro \
  -v ./docker_local/nginxpulse_data:/app/var/nginxpulse_data \
  -v ./docker_local/pgdata:/app/var/pgdata \
  -v ./docker_local/configs:/app/configs \
  -v /etc/localtime:/etc/localtime:ro \
  magiccoders/nginxpulse:latest

Important mount points: /share/logs – read‑only directory containing Nginx access logs. /app/var/nginxpulse_data – persistent application data. /app/var/pgdata – PostgreSQL data directory. /app/configs – configuration files. /etc/localtime – host time‑zone sync (required for correct timestamps).

After the container starts, open the UI at http://IP:8088. Ensure the time‑zone mount is present; otherwise timestamps will be offset.

2. Docker‑Compose

services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: local_nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    volumes:
      - ./docker_local/logs:/share/logs
      - ./docker_local/nginxpulse_data:/app/var/nginxpulse_data
      - ./docker_local/pgdata:/app/var/pgdata
      - ./docker_local/configs:/app/configs
      - /etc/localtime:/etc/localtime
    stop_grace_period: 90s
    restart: unless-stopped

Retain stop_grace_period: 90s so PostgreSQL can flush data before the container stops.

3. Stand‑alone Binary

Download the appropriate release from GitHub and run:

./nginxpulse
# or with explicit time‑zone
TZ=Asia/Shanghai ./nginxpulse

Versions ≥ 1.5.3 no longer embed SQLite; provide a PostgreSQL DSN in the configuration file ( database.dsn).

Multi‑Site Support

Multiple virtual hosts can be monitored simultaneously. Add each site in the initialization wizard or edit the JSON configuration, e.g.:

[
  {"name":"Site A","logPath":"/share/log/nginx/access-site-a.log","domains":["a.example.com"]},
  {"name":"Site B","logPath":"/share/log/nginx/access-site-b.log","domains":["b.example.com"]}
]

Compressed Log Handling

The tool can read .gz logs directly. Set logPath to a glob pattern such as: {"logPath":"/share/log/nginx/access-*.log.gz"} This avoids manual decompression of historic logs.

Permission Management

nginxpulse runs as a non‑root user inside the container. Ensure host directories are owned by the same UID/GID (e.g., 1000) or pass PUID and PGID environment variables:

# Example:
-docker run ... \
  -e PUID=1000 \
  -e PGID=1000 \
  ...

On SELinux‑enabled systems (RHEL/CentOS/Fedora) add the :z or :Z suffix to volume mounts, e.g.:

-v /path/to/logs:/var/log/nginx:ro,z

Do not use chmod -R 777 in production; it is insecure.

Common Issues & Fixes

No log details : Likely a permission problem; adjust host directory ownership to match the container user.

PV/UV always zero : Internal IPs are excluded by default; clear PV_EXCLUDE_IPS or set it to an empty array.

Incorrect timestamps : Mount /etc/localtime and re‑parse logs.

Data retention : Controlled by system.logRetentionDays (default 30 days).

Comparison with Similar Tools

Other Nginx log analysis solutions include GoAccess (CLI‑centric), ELK (resource‑heavy) and Prometheus + Nginx exporter (limited log insight). nginxpulse sits between them: easier to start than GoAccess and far lighter than ELK, making it suitable for small‑to‑medium sites that need quick visual traffic insights.

Conclusion

For servers running Nginx, nginxpulse provides a Docker‑first, open‑source solution to obtain PV/UV trends, IP geolocation, status‑code distribution, client breakdown and real‑time traffic without building a full ELK stack.

Source code: https://github.com/likaia/nginxpulse

Documentation: https://nginx-pulse-docs.kaisir.cn/