Improve docs

README.md

@@ -2,13 +2,15 @@
 
 Golang app for creating and resolving shortlinks for n8n workflows and URLs.
 
-Small learning project to get familiar with deployment best practices.
+Little learning project to get familiar with deployment and monitoring best practices.
+
+Live at: https://n8n.to
 
 Features:
 
 - Create + resolve shortlinks for n8n workflows and URLs
 - Optionally render n8n workflow shortlinks on canvas
-- Vanity URLs and password protection supported
+- Vanity URLs and password protection support
 - OpenAPI 3.0 spec + Swagger UI playground
 - Extensive integration test coverage
 - IP-address-based rate limiting
@@ -25,6 +27,9 @@ Deployment stack:
 - Uptime monitoring with UptimeRobot
 - Releases with GitHub Actions, GHCR, Docker
 
-## Author
+## Docs
 
-© 2024 Iván Ovejero
+- [`develop.md`](docs/develop.md)
+- [`release.md`](docs/release.md)
+- [`deploy.md`](docs/deploy.md)
+- [`monitor.md`](docs/monitor.md) 

deploy/scripts/start-services.sh

@@ -7,14 +7,8 @@ GITHUB_REPO=$(grep GITHUB_REPO $HOME/deploy/.config | cut -d'=' -f2 | tr -d '"*'
 
 RAW_REPO_ROOT="https://raw.githubusercontent.com/$GITHUB_USER/$GITHUB_REPO"
 
-# update docker-compose files
-curl -o deploy/docker-compose.monitoring.yml $RAW_REPO_ROOT/main/deploy/docker-compose.monitoring.yml
-curl -o deploy/docker-compose.yml $RAW_REPO_ROOT/main/deploy/docker-compose.yml
-
-docker-compose --file deploy/docker-compose.monitoring.yml pull
-docker-compose --file deploy/docker-compose.yml pull
+curl -o deploy/docker-compose.monitoring.yml $RAW_REPO_ROOT/master/deploy/docker-compose.monitoring.yml
+curl -o deploy/docker-compose.yml $RAW_REPO_ROOT/master/deploy/docker-compose.yml
 
 COMPOSE_PROJECT_NAME=n8n_shortlink docker-compose --file deploy/docker-compose.monitoring.yml up -d
-COMPOSE_PROJECT_NAME=n8n_shortlink docker-compose --file deploy/docker-compose.yml --profile production up -d
-
-# Adding `COMPOSE_PROJECT_NAME=n8n_shortlink` prevents Docker from prefixing volume names with this dir name.
+COMPOSE_PROJECT_NAME=n8n_shortlink docker-compose --file deploy/docker-compose.yml --profile production up -d

docs/deploy.md

@@ -63,11 +63,8 @@ deploy/scripts/vps-system-setup.sh
 
 - **Sentry**: Create a project and note down the **DSN**.
 - **AWS S3**: Create a bucket and note down the **bucket name**, **region**, **access key** and **secret**. Set a bucket lifecycle rule to delete files prefixed with `n8n-shortlink-backups` older than 10 days.
-- **DNS**: Add an A record pointing domain to IP address.
-- **GitHub**: Set up a repository. Create a **PAT** token with `read:packages` scope.
-- **Docker**: @TODO
-- **UptimeRobot**: Set up a monitor for the domain. Pause it. @TODO: Use Checkly
-@TODO: Add Makefile command to tail logs
+- **DNS**: Add A records for the `domain.com` and `grafana.domain.com`.
+- **GitHub**: Set up a repository. Create a **personal access token** with `read:packages` scope.
 
 ## 5. VPS tooling setup
 
@@ -107,7 +104,8 @@ echo '{
 }' > ~/.docker/config.json
 echo "N8N_SHORTLINK_SENTRY_DSN=$SENTRY_DSN" >> deploy/.env.production
 
+docker network create n8n-shortlink-network
 deploy/scripts/start-services.sh
 ```
 
-Unpause UptimeRobot monitor.
+Log in to `https://grafana.domain.com` and set a password for the Grafana admin user.

docs/develop.md

@@ -65,4 +65,8 @@ Sample requests for health and metrics:
 curl http://localhost:3001/health
 curl http://localhost:3001/metrics
 curl http://localhost:3001/debug/vars
-```
+```
+
+## TODOs
+
+- [ ] Add caching to `audit.yml`

docs/monitor.md

@@ -0,0 +1,27 @@
+# Monitor
+
+## Overview
+
+In the `n8n-shortlink-network` network, we have these monitoring-related services running:
+
+- http://n8n-shortlink:3001 → Shortlink API exposes Prometheus metrics, some of them derived from [expvar](https://pkg.go.dev/expvar).  
+- http://prometheus:9090 → [Prometheus](https://prometheus.io/) to scrape and aggregate metrics.
+- http://node_exporter:9100 → [Node Exporter](https://github.com/prometheus/node_exporter) to expose host metrics.
+- http://cadvisor:8080 → [cAdvisor](https://github.com/google/cadvisor) to expose container metrics.
+- http://loki:3100 → [Loki](https://grafana.com/oss/loki/) to aggregate logs from Promtail.
+- [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/) (no port exposed) to push logs to Loki.
+- http://grafana:3000 → [Grafana](https://grafana.com/) to visualize metrics and logs.
+
+Prometheus aggregates metrics from itself, the API, node exporter, cAdvisor. Loki aggregates logs from Promtail, which pushes them from the API and from the backup cronjob.
+
+Outside the network, to the reverse proxy, these services are available as `localhost:{port}`.
+
+## TODOs
+
+- [ ] Set up Grafana dashboards
+- [ ] Set up UptimeRobot or Checkly
+- [ ] Set up https://healthchecks.io/ for backup cronjob
+- [ ] Monitor DB
+- [ ] Makefile commands for server logs
+- [ ] Makefile commands for backups
+- [ ] Makefile command for Sentry

docs/release.md

@@ -1,14 +1,41 @@
 # Release
 
-Pull latest changes:
+Ensure local and remote `master` branches are in sync:
 
 ```sh
-git pull origin master
+git fetch origin
+git status
+# -> Your branch is up to date with 'origin/master'.
 ```
 
 Create tag (following semver) and push it:
 
 ```sh
 git tag v1.0.0
 git push origin v1.0.0
-```
+```
+
+Monitor the release on GitHub:
+
+- https://github.com/ivov/n8n-shortlink/actions/workflows/release-on-tag-push.yml
+
+On completion, this release is listed as `latest` on GHCR:
+
+- https://github.com/ivov/n8n-shortlink/pkgs/container/n8n-shortlink
+
+Deploy the release to production:
+
+```sh
+ssh shortlink_vps
+
+COMPOSE_PROJECT_NAME=n8n_shortlink docker-compose --file deploy/docker-compose.monitoring.yml down
+COMPOSE_PROJECT_NAME=n8n_shortlink docker-compose --file deploy/docker-compose.yml down
+deploy/scripts/start-services.sh
+```
+
+## TODOs
+
+- [ ] Shorten build time for `release-on-tag-push.yml`
+- [ ] Upgrade dependencies in `release-on-tag-push.yml`
+- [ ] Add GitHub release to `release-on-tag-push.yml`
+- [ ] Incorporate `check-build-health.yml` into `release-on-tag-push.yml`