README

Quick notes for running this repository (development & observability)

Running locally (development)

• Use the included compose files. To run the dev stack (overrides) set COMPOSE_ENV=dev so the correct env file is loaded:

  # run nginx on non-privileged ports (see .env.dev)
  COMPOSE_ENV=dev docker compose -f docker/docker-compose.prod.yml -f docker/docker-compose.dev.yml up -d --build
  

• By default the development nginx ports are set in .env.dev to avoid colliding with a host nginx. The defaults now are:

  • NGINX_HTTP_PORT=8080
  • NGINX_HTTPS_PORT=8444

Logging & observability (Loki + Promtail + Grafana)

• Promtail is configured to scrape /var/log/rad/*.log and push to Loki. Promtail's config is at docker/promtail-config.yml and the Loki config is at docker/loki-config/local-config.yaml.
• The nginx configs (both deploy/nginx/prod.conf and deploy/nginx/dev.conf) are configured to write access and error logs to /var/log/rad/nginx.access.log and /var/log/rad/nginx.error.log respectively.
• The compose files mount a host logs/ folder into /var/log/rad so both nginx (write) and promtail (read) can access the same files:
  • ../logs:/var/log/rad:rw (nginx)
  • ../logs:/var/log/rad:ro (promtail)

Host setup for logs

• Create the host logs folder at the repo root (this repo's logs/). In development you can use permissive permissions so containers can write to it quickly:

  mkdir -p logs
  # development: make writable by all (change this for production)
  sudo chown $USER:$USER logs
  chmod 0777 logs
  

• In production prefer setting the folder owner to the nginx worker UID (or run nginx under a specific user) and use 0755 or 0750 as appropriate. Example:

  # run on the host (determine nginx UID as needed)
  sudo chown -R 101:101 /srv/rad/logs
  sudo chmod 0755 /srv/rad/logs
  

Viewing logs in Grafana

• Grafana is available on the port exposed by compose (default 3000).

• The Loki datasource is configured to use http://loki:3100 (see compose). In Grafana Explore choose the Loki datasource and run queries such as:

  • {job="rad_app"} (all collected logs)
  • {job="rad_app", filename="/var/log/rad/nginx.access.log"}

Notes & recommendations

• In development the logs/ folder is ignored by git (/.gitignore updated). Do not commit runtime logs.
• Consider a log rotation/retention policy for production (e.g., logrotate or use Loki retention policies).
• If you need nginx to re-resolve the backend service IP without restarting, consider using resolver and variable-based upstreams in the nginx config. For many development workflows restarting nginx after web restarts is the simplest approach.

If you want, I can also add a short docs/OBSERVABILITY.md with more details and recommended production settings (TLS/auth for Loki, retention, log rotation).