docs: update production nginx/certificate section & admin troubleshooting (#793)

egekocabas · web-flow · commit f7b002d3eee2 · 2025-06-15T19:11:39.000+02:00
diff --git a/docs/admin/setup.rst b/docs/admin/setup.rst
@@ -121,39 +121,48 @@ Additional Containers
           --restart unless-stopped \
           -p 80:80 -p 443:443 \
           -v /etc/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
-          -v /etc/nginx/certs:/etc/nginx/certs:ro \
+          -v /var/lib/rbg-cert:/var/lib/rbg-cert:ro \
           --net helios-network \
           nginx:latest
 
+  The nginx configuration files for each environment are in the repository root as: ``nginx.prod.conf`` and ``nginx.staging.conf``. There is no automation to copy these files to the server; you must manually copy the appropriate file to ``/etc/nginx/conf/nginx.conf`` on the server.
+
+
   - **SSL/TLS Certificates**:
 
-  .. warning::
-    Do not forget to renew the certificates for both production and staging environments every 90 days!
+    We are using SSL certificates provided by TUM, which are officially issued and valid for 1 year.
+
+    The certificate files are symlinked to auto-generated paths within ``/var/lib/rbg-cert``, and nginx is configured to use them directly. Because these are symlinks, ``nginx`` only needs to be restarted once a year—when the certificates are renewed—to pick up the updated files.
 
-  Certificates are generated manually using Certbot. For example::
+    **Production**
 
-      sudo certbot certonly --standalone -d helios.aet.cit.tum.de
+    .. code-block:: nginx
 
-  This creates certificate files under ``/etc/letsencrypt``. After generating the certificates, update the nginx configuration file at ``/etc/nginx/conf/nginx.conf`` to reference the new certificate and key files. Typical SSL snippet in ``nginx.conf``::
+      ssl_certificate     /var/lib/rbg-cert/live/host:f:asevm84.cit.tum.de.fullchain.pem;
+      ssl_certificate_key /var/lib/rbg-cert/live/host:f:asevm84.cit.tum.de.privkey.pem;
 
-      server {
-          listen 443 ssl;
-          server_name helios.aet.cit.tum.de;
+    **Staging**
 
-          ssl_certificate     /etc/letsencrypt/live/helios.aet.cit.tum.de/fullchain.pem;
-          ssl_certificate_key /etc/letsencrypt/live/helios.aet.cit.tum.de/privkey.pem;
+    .. code-block:: nginx
 
-          # ... other configuration ...
-      }
+      ssl_certificate     /var/lib/rbg-cert/live/host:f:asevm90.cit.tum.de.fullchain.pem;
+      ssl_certificate_key /var/lib/rbg-cert/live/host:f:asevm90.cit.tum.de.privkey.pem;
 
-  Note that a reference version of the nginx configuration lives in the repository’s root as ``nginx.conf``—however, to see the live, up-to-date configuration in use, refer to the file at ``/etc/nginx/conf/nginx.conf``.
+    After each deployment from GitHub, the deployment script runs
 
-  - **Important**: After each deployment (``docker-compose up``), the deployment script runs::
+    .. code-block:: console
 
         docker restart nginx
 
     This ensures that nginx’s internal routing rules and certificate references are reloaded and point to the newly created container IPs.
 
+  .. warning::
+    The renewal process of certificates is handled by the TUM ITG team. Every year, we need to restart the nginx container to apply the new certificates.
+
+    .. code-block:: console
+
+      docker restart nginx
+
 
 Helios Network
 ---------------------
diff --git a/docs/admin/troubleshooting.rst b/docs/admin/troubleshooting.rst
@@ -8,6 +8,29 @@ Troubleshooting Helios
     :depth: 2
 
 
+How to Re-Deploy Helios from GitHub Actions
+--------------------------------------------
+
+To trigger a re-deployment of Helios without accessing the server manually, follow these steps using GitHub Actions:
+
+- Open the Helios GitHub Repository
+- Go to the Actions Tab
+- Select the Deployment Workflow
+
+  - Choose one of the deployment workflows:
+
+    - Build and Deploy to Prod
+    - Build and Deploy to Staging
+
+- Locate the "Deploy" step within the job summary.
+- Rerun the "Deploy" job
+
+  - It will bring down the current services with ``docker compose down``.
+  - A new ``.env`` file is generated dynamically using GitHub Environment secrets and variables (e.g., ``POSTGRES_PASSWORD``, ``NATS_URL``, etc.).
+  - The services are brought back up using ``docker compose up -d``.
+  - Finally, ``docker restart nginx`` is executed to reload routing and pick up any changes (e.g., environment updates or renewed TLS certificates).
+
+
 Updating SSL/TLS Certificates
 -------------------------------
 
@@ -22,52 +45,21 @@ Updating SSL/TLS Certificates
       --restart unless-stopped \
       -p 80:80 -p 443:443 \
       -v /etc/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
-      -v /etc/nginx/certs:/etc/nginx/certs:ro \
+      -v /var/lib/rbg-cert:/var/lib/rbg-cert:ro \
       --net helios-network \
       nginx:latest
 
   Once Nginx is running on the ``helios-network``, it will proxy traffic to the Helios services defined in Docker Compose.
 
-When your Let’s Encrypt certificates approach expiration (every 90 days), follow these steps to renew and apply them.
-
-1. **Renew Certificates**
-
-   Use Certbot in standalone mode to obtain or renew certificates for your Helios domain. Replace <your-domain> with your actual hostname (e.g., `helios.aet.cit.tum.de`):
-
-   .. code-block:: console
+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>`_.
 
-      sudo certbot certonly --standalone -d <your-domain>
+.. warning::
 
+  The only required action is to **restart** the ``nginx`` container **once a year** when the certificates are renewed:
 
-  This will generate or renew the certificate files under:
-  `/etc/letsencrypt/live/<your-domain>/fullchain.pem`
-  `/etc/letsencrypt/live/<your-domain>/privkey.pem`
-
-2. **Verify Nginx Configuration**
-
-Ensure your Nginx configuration references the correct certificate paths. Open the live Nginx config (not the repository copy) at `/etc/nginx/conf/nginx.conf` and confirm lines similar to:
-
-    .. code-block:: nginx
-
-        server {
-            listen 443 ssl;
-            server_name <your-domain>;
-
-            ssl_certificate     /etc/letsencrypt/live/<your-domain>/fullchain.pem;
-            ssl_certificate_key /etc/letsencrypt/live/<your-domain>/privkey.pem;
-
-            # …other configuration…
-        }
-
-3. **Reload or Restart Nginx Container**
-
-After certificates are in place and the config is correct, reload the Nginx container so it picks up the new files:
-
-    .. code-block:: console
-
-        docker restart nginx
+  .. code-block:: console
 
-    This command restarts the Nginx container, applying the new SSL/TLS certificates.
+      docker restart nginx
 
 NATS Webhook Data Cleanup
 -------------------------------
diff --git a/docs/contributor/setup.rst b/docs/contributor/setup.rst
@@ -3,7 +3,7 @@ Setup Guide
 ====================
 
 This guide focuses on setting up the Helios application on your local machine. The following sections will walk you through the necessary steps to install the required dependencies and run the application.
-The production setup is covered in the `Production Setup Guide <production_setup.html>`_.
+The production setup is covered in the `Production Setup Guide <../admin/setup.html>`_.
 
 
 Prerequisites
diff --git a/nginx.prod.conf b/nginx.prod.conf
@@ -29,8 +29,8 @@ http {
         listen 443 ssl;
         server_name helios.aet.cit.tum.de;
 
-        ssl_certificate $SSL_CERT_PATH;
-        ssl_certificate_key $SSL_KEY_PATH;
+        ssl_certificate /var/lib/rbg-cert/live/host:f:asevm84.cit.tum.de.fullchain.pem;
+        ssl_certificate_key /var/lib/rbg-cert/live/host:f:asevm84.cit.tum.de.privkey.pem;
 
 
         location / {
diff --git a/nginx.staging.conf b/nginx.staging.conf
@@ -0,0 +1,121 @@
+# Main configuration directives
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+# Events block
+events {
+    worker_connections 1024;
+}
+
+# HTTP block
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Docker's internal DNS resolver
+    # When the compose is restarted, the IP addresses of the services might change
+    # This is required for resolving the service names to their IP addresses
+    resolver 127.0.0.11 ipv6=off;
+
+    # SSL Settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # First server block for HTTPS
+    server {
+        listen 443 ssl;
+        server_name helios-staging.aet.cit.tum.de;
+
+        ssl_certificate /var/lib/rbg-cert/live/host:f:asevm90.cit.tum.de.fullchain.pem;
+        ssl_certificate_key /var/lib/rbg-cert/live/host:f:asevm90.cit.tum.de.privkey.pem;
+
+
+        location / {
+            # Forward to webapp on port 80
+            proxy_pass http://client:80;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        # Proxy API requests
+        location /api {
+            proxy_pass http://application-server:8080;  # Forward to application server
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        # Proxy Keycloak requests
+        location ~* ^/(realms|resources|robots\.txt) {
+            proxy_pass http://keycloak:8081;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto https;
+            proxy_set_header X-Forwarded-Port 443;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        # Keycloak admin console
+        location /admin {
+            proxy_pass http://keycloak:8081/admin;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto https;
+            proxy_set_header X-Forwarded-Port 443;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        location /github {
+            # Only allow POST requests
+            limit_except POST {
+                deny all;
+            }
+
+            # Validate required GitHub headers
+            set $valid_headers 1;
+
+            if ($http_x_github_event = "") {
+                set $valid_headers 0;
+            }
+            if ($http_x_github_delivery = "") {
+                set $valid_headers 0;
+            }
+            if ($http_x_hub_signature_256 = "") {
+                set $valid_headers 0;
+            }
+
+            # Deny access if headers are invalid
+            if ($valid_headers = 0) {
+                return 403;
+            }
+
+            # Forward to the webhook listener service
+            proxy_pass http://webhook-listener:4200;  # Forward to webhook listener on port 4200
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
+    }
+
+    # Second server block for HTTP to HTTPS redirection
+    server {
+        listen 80;
+        server_name helios-staging.aet.cit.tum.de;
+
+        return 301 https://$host$request_uri;
+    }
+}
