docs: refactor helios docs (#808)

Author: egekocabas

.env.example

@@ -8,11 +8,6 @@ DATASOURCE_PASSWORD=helios
 NATS_SERVER=nats-server:4222
 NATS_AUTH_TOKEN=5760e8ae09adfb2756f9f8cd5cb2caa704cd3f549eaa9298be843ceb165185d815b81f90c680fa7f626b7cd63abf6ac9
 WEBHOOK_SECRET=123
-REPOSITORY_NAME=
-ORGANIZATION_NAME=
-GITHUB_AUTH_TOKEN=
-RUN_ON_STARTUP_COOLDOWN=0
 KC_HOSTNAME=localhost
 KEYCLOAK_ADMIN=admin
-KEYCLOAK_ADMIN_PASSWORD=admin
-HELIOS_CLIENT=http://localhost:4200
+KEYCLOAK_ADMIN_PASSWORD=admin

docs/_static/images/setup/app-name.png

@@ -0,0 +1,35 @@
+========================
+Monitoring
+========================
+
+
+.. contents:: Content of this document
+    :local:
+    :depth: 2
+
+
+
+Overview
+-----------------
+
+This page explains how we monitor the production Helios deployment today. We currently rely on:
+
+- Grafana for metrics, dashboards and ad‑hoc investigations.
+- Sentry for error tracking (client and backend).
+
+
+Links
+-----------------
+
+- Grafana: https://grafana.gchq.ase.in.tum.de/  (login via Keycloak)
+- Sentry (client): https://sentry.aet.cit.tum.de/organizations/aet/projects/helios-client/?project=4
+- Sentry (backend): https://sentry.aet.cit.tum.de/organizations/aet/projects/helios-server/?project=5
+
+
+Access & Permissions
+-----------------------
+
+To get full access, please do both of the following.
+
+1. **Sentry access**: Ask the admins to **add you to the relevant Sentry group** with permissions over the Helios projects.
+2. **Grafana access**: Ask the admins to **add you to the Helios dashboard** since Helios dashboard is not publicly accessible.

docs/_static/images/setup/ngrok-webhook.png

@@ -1,5 +1,5 @@
 ========================
-Production Setup Guide
+Production VM Guide
 ========================
 
 .. contents:: Content of this document
@@ -11,6 +11,8 @@ We maintain two servers: one for production and one for staging:
 - Production server: ``https://helios.aet.cit.tum.de/``
 - Staging server:    ``https://helios-staging.aet.cit.tum.de/``
 
+Only required package is **Docker**. The production server runs the latest stable version of Helios (``main`` branch), while the staging server runs the latest development version (``staging`` branch).
+
 Both environments use the same Compose file:
 
 - ``compose.prod.yml`` is used for both production and staging deployments.
@@ -68,14 +70,224 @@ File Descriptions
   The PEM file for the GitHub App.
 
   - Used as credentials when making API requests to GitHub.
-  - This file is generated by following the **Generate the Private Key** step in the `Creating a GitHub App <../local/setup.html#creating-a-github-app>`_.
+  - This file is generated by following the **Generate the Private Key** step in the `Creating a GitHub App <../../contributor/setup#creating-a-github-app:~:text=Generate%20the%20Private%20Key>`_.
 
 - ``helios-realm.json``
   An exported Keycloak realm configuration.
 
   - Instead of wiping the database, we export/import Keycloak settings via this file.
   - It contains client IDs, client secrets, login page settings, token exchange rules, etc.
 
+
+Environment Variables
+------------------------
+
+The ``.env`` file in ``/opt/helios`` contains all environment variables for production/staging deployments. GitHub Actions fills this file during deployment.
+
+Below is the complete list of variables, their purpose, and where they are used.
+
+Core Infrastructure
+~~~~~~~~~~~~~~~~~~~
+
+- ``ENVIRONMENT``
+  Environment identifier (``prod``, ``staging``, ``dev``).
+  *Status:* **Unused in compose** (informational only).
+
+- ``POSTGRES_DB``
+  Name of the PostgreSQL database for the application.
+  *Used by:* ``postgres`` (also Keycloak indirectly via DB creation).
+
+- ``POSTGRES_PASSWORD``
+  PostgreSQL password.
+  *Used by:* ``postgres``, ``keycloak``.
+
+- ``POSTGRES_USER``
+  PostgreSQL username.
+  *Used by:* ``postgres``, ``keycloak``.
+
+- ``SPRING_PROFILES_ACTIVE``
+  Spring Boot active profile (``prod`` for production).
+  *Used by:* ``application-server``, ``notification``.
+
+- ``DATASOURCE_URL``
+  JDBC connection string to PostgreSQL.
+  *Used by:* ``application-server``.
+
+- ``DATASOURCE_USERNAME``
+  DB username for application server JDBC. Should match ``POSTGRES_USER``.
+  *Used by:* ``application-server``.
+
+- ``DATASOURCE_PASSWORD``
+  DB password for application server JDBC. Should match ``POSTGRES_PASSWORD``.
+  *Used by:* ``application-server``.
+
+NATS Messaging
+~~~~~~~~~~~~~~
+
+- ``NATS_SERVER``
+  Host:port of NATS server.
+  *Used by:* ``application-server``, ``notification``.
+
+- ``NATS_AUTH_TOKEN``
+  Token for authenticating with NATS.
+  *Used by:* ``nats-server``, ``webhook-listener``, ``application-server``, ``notification``.
+
+- ``NATS_DURABLE_CONSUMER_NAME``
+  Durable consumer name for message replay.
+  *Used by:* ``application-server`` (value for ``notification`` is written hardcoded in ``compose.prod.yaml`` as ``notification-consumer``).
+
+- ``NATS_CONSUMER_INACTIVE_THRESHOLD_MINUTES``
+  Consumer inactivity threshold.
+  *Used by:* ``application-server``, ``notification``.
+
+- ``NATS_CONSUMER_ACK_WAIT_SECONDS``
+  Ack wait time for durable consumers.
+  *Used by:* ``application-server``, ``notification``.
+
+GitHub App / Repository Sync
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``WEBHOOK_SECRET``
+  HMAC secret for GitHub webhook validation.
+  *Used by:* ``webhook-listener``.
+
+- ``REPOSITORY_NAME``
+  Comma-separated list of repositories to sync. This value can be empty since all the repositories which install the GitHub App will be synced automatically.
+  *Used by:* ``application-server``.
+
+- ``ORGANIZATION_NAME``
+  GitHub organization name for auto-detection of installation ID.
+  *Used by:* ``application-server``.
+  *Note:* Set this value and leave ``GITHUB_INSTALLATION_ID`` empty for auto-detection of the GitHub App installation ID.
+
+- ``GITHUB_AUTH_TOKEN``
+  GitHub Personal Access Token (if not using GitHub App, we are right now using the GitHub App, so leave this empty).
+  *Used by:* ``application-server``.
+
+- ``RUN_ON_STARTUP_COOLDOWN``
+  Minimum minutes since last sync to run sync on startup.
+  *Used by:* ``application-server``.
+
+- ``SENTRY_DSN``
+  Sentry DSN for error reporting.
+  *Used by:* ``application-server``.
+
+- ``DATA_SYNC_RUN_ON_STARTUP``
+  Whether to run repository sync on startup. Deploying a new version takes couple of minutes, setting this value to ``false``is safe since syncing takes quite some time and we do not want to run it on every deployment.
+  *Used by:* ``application-server``.
+
+- ``GITHUB_APP_NAME``
+  GitHub App URL-safe name.
+  *Used by:* ``application-server``.
+
+- ``GITHUB_APP_ID``
+  Numeric ID of GitHub App.
+  *Used by:* ``application-server``.
+
+- ``GITHUB_CLIENT_ID``
+  OAuth Client ID for GitHub App.
+  *Used by:* ``application-server``.
+
+- ``GITHUB_INSTALLATION_ID``
+  GitHub App installation ID. Empty if auto-detecting.
+  *Used by:* ``application-server``.
+
+- ``GITHUB_PRIVATE_KEY_PATH``
+  Path to PKCS#8-formatted GitHub App private key.
+  *Used by:* ``application-server``.
+
+Authentication / Keycloak
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``KC_BOOTSTRAP_ADMIN_USERNAME``
+  Initial Keycloak admin username.
+  *Used by:* ``keycloak``.
+
+- ``KC_BOOTSTRAP_ADMIN_PASSWORD``
+  Initial Keycloak admin password.
+  *Used by:* ``keycloak``.
+
+- ``KC_HOSTNAME``
+  Public hostname for Keycloak.
+  *Used by:* ``keycloak``.
+
+- ``KC_HTTP_ENABLED``
+  Whether to enable HTTP in Keycloak.
+  *Used by:* ``keycloak``.
+
+- ``OAUTH_ISSUER_URL``
+  Keycloak realm issuer URL.
+  *Used by:* ``application-server``.
+
+- ``HELIOS_TOKEN_EXCHANGE_CLIENT``
+  Keycloak client ID for token exchange.
+  *Used by:* ``application-server``.
+
+- ``HELIOS_TOKEN_EXCHANGE_SECRET``
+  Keycloak client secret for token exchange.
+  *Used by:* ``application-server``.
+
+Notification Service
+~~~~~~~~~~~~~~~~~~~~
+
+- ``MAIL_HOST``
+  SMTP host for sending emails.
+  *Used by:* ``notification``.
+
+- ``MAIL_PORT``
+  SMTP port.
+  *Used by:* ``notification``.
+
+- ``EMAIL_ENABLED``
+  Enable/disable email sending.
+  *Used by:* ``notification``.
+
+- ``EMAIL_FROM``
+  Sender email address.
+  *Used by:* ``notification``.
+
+Image Tags (Deployment Control)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``CLIENT_IMAGE_TAG``
+  Docker image tag for client.
+  *Used by:* ``client``.
+
+- ``APPLICATION_SERVER_IMAGE_TAG``
+  Docker image tag for application server.
+  *Used by:* ``application-server``.
+
+- ``NOTIFICATION_SERVER_IMAGE_TAG``
+  Docker image tag for notification service.
+  *Used by:* ``notification``.
+
+- ``WEBHOOK_LISTENER_IMAGE_TAG``
+  Docker image tag for webhook listener.
+  *Used by:* ``webhook-listener``.
+
+- ``KEYCLOAK_IMAGE_TAG``
+  Docker image tag for Keycloak.
+  *Used by:* ``keycloak``.
+
+Other Application Server Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``CLEANUP_WORKFLOW_RUN_DRY_RUN``
+  If true, cleanup workflow runs in dry-run mode.
+  *Used by:* ``application-server``.
+
+- ``HELIOS_ENVIRONMENT_NAME``
+  Used for push-based status updates to Helios.
+  *Used by:* ``application-server``.
+
+- ``HELIOS_PROD_SECRET_KEY``
+  Used for push-based status updates to Helios.
+  *Used by:* ``application-server``.
+
+- ``HELIOS_STAGING_SECRET_KEY``
+  Used for push-based status updates to Helios.
+  *Used by:* ``application-server``.
+
 Runtime Containers
 ------------------
 

docs/_static/images/setup/organization-name.png

@@ -51,7 +51,7 @@ Updating SSL/TLS Certificates
 
   Once Nginx is running on the ``helios-network``, it will proxy traffic to the Helios services defined in Docker Compose.
 
-We are using SSL/TLS certificates are provided by the TUM IT department and are valid for 1 year. These certificates are automatically renewed by ITG and exposed via symlinks under ``/var/lib/rbg-cert/live/``. Nginx is configured to use these paths directly in both staging and production environments. For more details and the relevant ``nginx.conf`` certificate paths, refer to the `Production Setup Guide -> Additional Containers -> nginx <setup.html#additional-containers>`_.
+We are using SSL/TLS certificates are provided by the TUM IT department and are valid for 1 year. These certificates are automatically renewed by ITG and exposed via symlinks under ``/var/lib/rbg-cert/live/``. Nginx is configured to use these paths directly in both staging and production environments. For more details and the relevant ``nginx.conf`` certificate paths, refer to the `Production Setup Guide -> Additional Containers -> nginx <../setup#additional-containers>`_.
 
 .. warning::