Skip to content

Configuration EN

Jump to bottom
likai edited this page Apr 25, 2026 · 14 revisions

Configuration

This page focuses on getting NginxPulse configured quickly. Full field details, log sources, and log format examples are split into dedicated pages to keep this entry point lightweight.

Config Location

  • Default config: configs/nginxpulse_config.json
  • Local development: scripts/dev_local.sh uses configs/nginxpulse_config.dev.json
  • Environment injection: CONFIG_JSON or WEBSITES

Minimal Config

If the log file and PostgreSQL are reachable, start with this:

{
  "websites": [
    {
      "name": "Main Site",
      "logPath": "/var/log/nginx/access.log",
      "domains": ["example.com", "www.example.com"],
      "logType": "nginx"
    }
  ],
  "database": {
    "driver": "postgres",
    "dsn": "postgres://nginxpulse:nginxpulse@127.0.0.1:5432/nginxpulse?sslmode=disable"
  },
  "server": {
    "Port": ":8089"
  }
}

Fields You Usually Need To Change

  • websites[].name: site name. It is used to derive the site ID; renaming creates a new site.
  • websites[].logPath: log path. For remote, multi-source, or Agent collection, see Log Sources.
  • websites[].domains: domain list. Recommended for same-site referer detection.
  • websites[].logType: log type. Supported values and samples are in Supported Log Formats.
  • websites[].autoDiscoverHosts: use this entry as a discovery template and generate real sites from parsed host values.
  • database.dsn: PostgreSQL connection string.
  • server.Port: Web/API listen port. :8089 is the common default.

Common Scenarios

Local or Container Nginx Logs

{
  "name": "Main Site",
  "logPath": "/var/log/nginx/access.log",
  "domains": ["example.com", "www.example.com"],
  "logType": "nginx"
}

For rotated daily logs, use a glob:

{
  "name": "Main Site",
  "logPath": "/var/log/nginx/access-*.log",
  "domains": ["example.com"],
  "logType": "nginx"
}

Docker-Mounted Logs

The config must use the path inside the container, not the host path:

volumes:
  - /var/log/nginx:/share/logs/nginx:ro
{
  "name": "Main Site",
  "logPath": "/share/logs/nginx/access.log",
  "domains": ["example.com"],
  "logType": "nginx"
}

Multiple Sites

{
  "websites": [
    {
      "name": "Main Site",
      "logPath": "/share/logs/nginx/main-access.log",
      "domains": ["example.com", "www.example.com"],
      "logType": "nginx"
    },
    {
      "name": "Blog",
      "logPath": "/share/logs/nginx/blog-access.log",
      "domains": ["blog.example.com"],
      "logType": "nginx"
    }
  ]
}

Host-Based Site Auto Discovery

In plain terms: before this feature, you had to tell NginxPulse which sites exist. With this feature, NginxPulse can read the domain from logs first, then create sites automatically.

Previously, if one Nginx / Nginx Proxy Manager instance hosted many domains, you usually had to configure each site manually:

{
  "name": "a.com",
  "logPath": "/share/logs/nginx/access.log",
  "domains": ["a.com"],
  "logFormat": "... $host"
},
{
  "name": "b.com",
  "logPath": "/share/logs/nginx/access.log",
  "domains": ["b.com"],
  "logFormat": "... $host"
}

If you later add c.com, you also need to add another site config.

With autoDiscoverHosts, you only configure one discovery template. NginxPulse periodically scans matching logs, extracts domains from the host field, and registers real sites by domain. For example, if the logs contain a.com, b.com, and c.com, the site selector will show those 3 sites; each site only counts log entries for its own domain.

The requirement is that the log format must include a domain field, such as $host or $http_host. If the logs only contain IP, time, and URL, NginxPulse cannot know which site a request belongs to.

nginx-proxy-manager can use the built-in log type directly:

{
  "name": "NPM Auto Discover",
  "logPath": "/share/logs/npm/proxy-host-*_access.log",
  "logType": "nginx-proxy-manager",
  "autoDiscoverHosts": true
}

Plain Nginx or custom logs also work as long as logFormat / logRegex can parse a host value. For example:

{
  "name": "Host Auto Discover",
  "logPath": "/share/logs/nginx/*.log",
  "logFormat": "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $host",
  "autoDiscoverHosts": true
}

If you use logRegex, include a named group like (?P<host>...).

Remote Logs or Multi-Source Collection

When logs are not on the NginxPulse host/container, use websites[].sources:

{
  "name": "Main Site",
  "domains": ["example.com"],
  "sources": [
    {
      "id": "sftp-main",
      "type": "sftp",
      "host": "10.0.0.10",
      "port": 22,
      "user": "nginx",
      "auth": { "keyFile": "/home/nginxpulse/.ssh/id_ed25519" },
      "path": "/var/log/nginx/access.log",
      "compression": "auto"
    }
  ],
  "logType": "nginx"
}

More local, sftp, http, s3, and agent examples are in Log Sources.

Custom Log Format

If no built-in logType matches your logs, prefer logFormat:

{
  "name": "Custom Site",
  "logPath": "/var/log/custom/access.log",
  "logFormat": "$remote_addr [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\""
}

Custom fields and full examples are in Supported Log Formats.

Reverse Proxy Subpath

To serve NginxPulse under /nginxpulse/:

{
  "system": {
    "webBasePath": "nginxpulse"
  }
}

Result:

  • Web: /nginxpulse/
  • Mobile: /nginxpulse/m/
  • API: /nginxpulse/api/

Note: webBasePath only supports one path segment. Restart the service after changing it.

Detailed Docs

Clone this wiki locally