# ngxstat

`ngxstat` is a lightweight log analytics toolkit for Nginx. It imports access
logs into an SQLite database and renders static dashboards so you can explore
per-domain metrics without running a heavy backend service.

## Requirements

* Python 3.10+
* Access to the Nginx log files (default: `/var/log/nginx`)

The helper scripts create a virtual environment on first run, but you can also
set one up manually:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Importing Logs

Run the importer to ingest new log entries into `database/ngxstat.db`:

```bash
./run-import.sh
```

Rotated logs are processed in order and only entries newer than the last
imported timestamp are added.

## Generating Reports

To build the HTML dashboard and JSON data files use `run-reports.sh` which runs
all intervals in one go:

```bash
./run-reports.sh
```

The script calls `scripts/generate_reports.py` internally to create hourly,
daily, weekly and monthly reports, then writes analysis JSON files used by the
"Analysis" tab. Per-domain reports are written under `output/domains/<domain>`
alongside the aggregate data. Open `output/index.html` in a browser to view the
dashboard.

If you prefer to run individual commands you can invoke the generator directly:

```bash
python scripts/generate_reports.py hourly
python scripts/generate_reports.py daily --all-domains
```

## Analysis Helpers

`run-analysis.sh` executes additional utilities that examine the database for
missing domains, caching opportunities and potential threats. The JSON output is
saved under `output/analysis` and appears in the "Analysis" tab. The
`run-reports.sh` script also generates these JSON files as part of the build.

## UX Controls

The dashboard defaults to a 7‑day window for time series. Your view preferences
persist locally in the browser under the `ngxstat-state-v2` key. Use the
"Reset view" button to clear saved state and restore defaults.

```bash
./run-analysis.sh
```

## Serving the Reports

The generated files are static. You can serve them with a simple Nginx block:

```nginx
server {
    listen 80;
    server_name example.com;
    root /path/to/ngxstat/output;

    location / {
        try_files $uri $uri/ =404;
    }
}
```

Restrict access if the reports should not be public.

## Running Tests

Install the development dependencies and execute the suite with `pytest`:

```bash
pip install -r requirements.txt
pytest -q
```

All tests must pass before submitting changes.

## Acknowledgements

ngxstat uses the following third‑party resources:

* [Chart.js](https://www.chartjs.org/) for charts
* [DataTables](https://datatables.net/) and [jQuery](https://jquery.com/) for table views
* [Bulma CSS](https://bulma.io/) for styling
* Icons from [Free CC0 Icons](https://cc0-icons.jonh.eu/) by Jon Hicks (CC0 / MIT)
* [Typer](https://typer.tiangolo.com/) for the command-line interface
* [Jinja2](https://palletsprojects.com/p/jinja/) for templating

The project is licensed under the GPLv3. Icon assets remain in the public domain
via the CC0 license.