# Nomad Trail This directory contains a Nomad job specification (`trail.nomad.hcl`) that deploys [Trail](https://github.com/open-wander/trail), a self-hosted web analytics platform for reverse proxies. Trail reads access logs directly from Traefik, Apache, or Nginx and serves a real-time htmx dashboard. No JavaScript tracking required. ## Prerequisites - [Nomad](https://developer.hashicorp.com/nomad/docs/install) installed and running. - [Docker](https://docs.docker.com/get-docker/) installed (since the job uses the Docker driver). - A reverse proxy writing access logs to a known host path. ## Host Setup Create the data directory on each Nomad client that may run this job: ```bash mkdir -p /opt/trail/data ``` ## Usage ### 1. Validate the Job Before running the job, you can validate the syntax of the job file: ```bash nomad job validate trail.nomad.hcl ``` ### 2. Plan the Job Run a plan to see what changes Nomad will make: ```bash nomad job plan trail.nomad.hcl ``` ### 3. Run the Job Submit the job to your Nomad cluster: ```bash nomad job run trail.nomad.hcl ``` ### 4. Check Job Status Verify the status of the job: ```bash nomad job status trail ``` To see the logs of the allocations: ```bash nomad alloc logs <alloc-id> ``` (Replace `<alloc-id>` with the actual allocation ID from the status command). ### 5. Stop the Job To stop and purge the job: ```bash nomad job stop -purge trail ``` ## Variables | Variable | Default | Description | |---|---|---| | `datacenters` | `["dc1"]` | List of datacenters to deploy to | | `trail_version` | `latest` | Trail Docker image tag | | `host_log_path` | `/var/log/traefik` | Host path to the reverse proxy access log directory | | `host_data_path` | `/opt/trail/data` | Host path for persistent Trail data (SQLite DB) | | `log_file` | `/logs/access.log` | Path to access log inside the container | | `log_format` | `auto` | Log format: `auto`, `traefik`, `apache`, or `nginx` | | `retention_days` | `90` | Number of days to retain analytics data | | `htpasswd_file` | `""` | Host path to htpasswd file for basic auth (empty to disable) | | `geoip_path` | `""` | Path to GeoIP database inside the container (empty to disable) | | `service_provider` | `nomad` | Service discovery provider (`nomad` or `consul`) | | `traefik_host` | `""` | Hostname for Traefik routing (empty to disable Traefik tags) | ### Examples Minimal deployment reading Traefik logs: ```bash nomad job run \ -var='host_log_path=/var/log/traefik' \ trail.nomad.hcl ``` With Traefik routing and basic auth: ```bash nomad job run \ -var='host_log_path=/var/log/traefik' \ -var='traefik_host=stats.example.com' \ -var='htpasswd_file=/etc/trail/.htpasswd' \ trail.nomad.hcl ``` Reading Nginx logs with 30-day retention: ```bash nomad job run \ -var='host_log_path=/var/log/nginx' \ -var='log_format=nginx' \ -var='retention_days=30' \ trail.nomad.hcl ``` ## Job Details - **Job Name**: `trail` - **Type**: `service` - **Task Group**: `trail` - **Task**: `trail` (uses `ghcr.io/open-wander/trail` Docker image) - **Resources**: 200 MHz CPU, 256 MB Memory - **Network**: Exposes port 8080 (mapped to dynamic `http` port) - **Persistence**: SQLite database stored on host volume at `host_data_path`