From d29c23a7997ee330f3cdf67f1bb0c08a2030d284 Mon Sep 17 00:00:00 2001
From: Ross <xkjq@ymail.com>
Date: Mon, 8 Dec 2025 09:54:15 +0000
Subject: [PATCH] .

---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..f10b7633
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+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:
+
+  ```sh
+  # 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:
+
+  ```sh
+  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:
+
+  ```sh
+  # 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).