Documentation: Reverse Proxy Warning

[gounthar]

Replaces #61. This is based on an email discussion between Jean-Marc, Bervianto and myself.
Please have a look @berviantoleo @ash-sxn @jmMeessen and @MarkEWaite, @dduportal if you have time.

Description:

The issue is related to the broken reverse proxy warning occurring, especially on GitPod. The warning is triggered because Jenkins listens on URL:8080 but receives requests on URL:443 due to GitPod's infrastructure constraints. Although the warning does not break the tutorials, it would be beneficial to suppress it.

Recommended Solution:

The recommended approach is to suppress the administrative monitor warning for the broken reverse proxy. This can be achieved through the JCasC (Jenkins Configuration as Code) configuration. The following configuration should be added to the Jenkins configuration to disable the warning:

jenkins:
  (...)
  disabledAdministrativeMonitors:
  - "hudson.diagnosis.ReverseProxySetupMonitor"

This setting can also be used on the local installation to prevent the warning.

Agreed Solution:

Both mentors, Jean-Marc and Bervianto, agree with the suppression of the warning and adding documentation about the suppression. The focus should be on the critical objectives of the project, and fixing the warning is not a priority.

Previous Attempts:

Previous attempts to force the protocol within GitPod using the gp ports protocol command did not solve the problem. The protocol remained as HTTPS instead of HTTP. Also, configuration attempts using .gitpod.yml did not result in the expected protocol change.

Future Action:

The agreed-upon solution is to document the warning suppression and use JCasC to eliminate the warning. Although it may not be an ideal solution, it will be a step forward in progress.

Documentation:

Documentation about the suppression of the warning and the use of JCasC should be provided for future maintainers and readers to understand the reasoning behind the decision.

[dduportal]

Note for later improvements (e.g. not priority and nice to have, not mandatory at all): https://www.gitpod.io/docs/configure/workspaces/ports#accessing-port-urls states that you can use the gh port command to programmaticaly retrieve the exposed URL.

With a JCasc configured to set up the Jenkins URL from an environment variable passed by docker, you can think about an automatic setup in the case of GitPod (commands in the .gitpod.yml`)

# In the gitpod yaml
export JENKINS_EXT_URL="$(gp port 8080)"

# Everywhere: laptops, gitpods, etc.
docker compose up --detach --build --force-recreate

with something like this:

# docker-compose.yml
services:
  jenkins:
    # ...
    environment:
      - JENKINS_EXT_URL=${JENKINS_EXT_URL:-http://localhost:8080} # Default to localhost:8080 with HTTP
# ...

and

# JCasc
# ...
unclassified:
  location:
    url: "${JENKINS_EXT_URL}"

[gounthar]

That's a clever approach! Thank you for providing this information.

However, I have noticed one drawback. Even after correctly setting up the URL within JCASC, Jenkins is still raising complaints about the configuration. It seems there might be some hidden tricks in the GitPod setup that we are not yet aware of.