Promtail is the log shipper for Smithflix. It tails host logs, NPM logs, and Docker JSON logs, enriches them with labels and parsing stages, and pushes them into Loki.
This page documents the promtail service. It does not replace the Loki page.
- Container:
promtail
- Image:
grafana/promtail:latest
- Stack: Logs Stack
- Compose path:
/opt/stacks/logs/compose.yaml
- Docker network:
logs_loki
- Restart policy:
unless-stopped
- No container healthcheck is configured as of
2026-04-07
- No host port is published
¶ Config and Data Paths
- Main config:
/srv/docker/promtail/promtail-config.yml
- Positions file:
/srv/docker/promtail/positions.yaml
- Writable state directory:
/srv/docker/promtail
- Mounted log sources include
/var/log, /var/lib/docker/containers, /srv/docker/nginx/data/logs, and /home/dockeruser/netcheck/log/connection.log
- Docker socket is mounted read-only for container discovery
- Internal HTTP listener: port
9080 as configured in promtail-config.yml
- No LAN host binding or public proxy hostname was verified on
2026-04-07
- Loki client target is
http://loki:3100/loki/api/v1/push
¶ Authentication and Secret Locations
- No Promtail-specific secret file or public auth surface was verified on
2026-04-07
- Treat Promtail as an internal log-ingestion component only
- The current config ships host logs for
syslog, auth.log, kern.log, fail2ban, pelican/wings.log, and the netcheck connection log
- NPM access and error logs are tailed from
/srv/docker/nginx/data/logs
- Docker log discovery is enabled through the Docker socket and includes service-specific parsing stages for Arr apps, Bazarr, SABnzbd, Jellyseerr, Home Assistant, Tdarr, Cleanuparr, TVHeadend, Dockge, Pelican, Watchtower, and others
- If a service changes log format, update Promtail parsing before assuming Loki or Grafana is broken
¶ Monitoring and Logs
- Docker logging driver is
json-file
- Recent logs showed Promtail detecting new NPM proxy-host log files and tailing them immediately
- Recent logs also showed successful completion of a Docker log transfer for the Wiki.js container after the wiki rollout
- Because Promtail has no container healthcheck, verify actual ingestion in Loki when troubleshooting
¶ Backup and Restore
/srv/docker/promtail is in the documented Duplicati scope because it lives under /srv/docker- Restore should preserve both
promtail-config.yml and positions.yaml
- The compose definition lives in
/opt/stacks/logs/compose.yaml
¶ Failure Modes and Recovery
- Log-format drift can silently break label extraction while leaving ingestion superficially functional
- If mounted host paths or the Docker socket become unavailable, Promtail will lose visibility into part of the platform without necessarily crashing
- Replacing
positions.yaml carelessly can cause duplicate or skipped ingestion during recovery