Create 'Reverse proxy configuration' page(s) on jenkins.io

[MarkEWaite]

Use the documentation page conversion instructions to convert Jenkins behind an NGinX reverse proxy and related pages from wiki to jenkins.io ASCIIDoc.

Related Wiki Pages to migrate

Some other wiki pages related to this "Jenkins behind a reverse-proxy" topic:

• Jenkins says my reverse proxy setup is broken
• Running Jenkins behind Apache
• Running Jenkins on Port 80 or 443 using iptables
• JenkinsBehindProxy
• Jenkins behind HAProxy
• Jenkins behind Squid
• Jenkins behind IIS

Topic to highlight in the new doc page

These topics are user oriented and should guide end users (persona: Jenkins admin) whatever reverse proxy solution is used:

• Landing page for "Jenkins says my reverse proxy is broken" (redirected from wiki page)
• Expose Jenkins to public ports (hostname and port mapping public <-> topic in relation with how Jenkins generates its pages, links and the $JENKINS_URL configuration item)
• HTTP+TLS with Jenkins:
  • Outside Jenkins (TLS termination at reverse-proxy level)
  • Inside Jenkins (End to end encryption with a reverse proxy, either with TLS passtrough or with 2 level termination)
• Exposing Agent protocol:
  • JNLPv4 (TCP reverse-proxying )
  • Websockets (HTTP reverse-proxying)
• Loadbalancing:
  • Healthcheck for Jenkins master ("how to check if Jenkins is alive to decide sending traffic to it")
  • State clearly the "no horizontal scaling of the Jenkins master" for newcomers not aware of the "stateful" context
• Authentication: passing HTTP headers to Jenkins in the context of a reverse proxy, to ensure any authN realm works (Github, SAML, LDAP, oAUTH, etc.) when redirections happen

Food for Thought

Some food for thought here (that might or might not be integrated):

• Proposal of other integrations (as they come of a lot):
  • Jenkins with HAProxy
  • Jenkins with Traefik

[zbynek]

This page seems to provide a subset of the information from
https://wiki.jenkins.io/display/JENKINS//Running+Jenkins+behind+Nginx
mentioned in
#3218

[MarkEWaite]

Agreed @zbynek. Thanks very much! Next phase of this process is to identify the overlapping pages (as you just did) and define final destinations for a merge of the various pages that provide information.

My initial thought was that we should add two new pages to jenkins.io:

• Jenkins with Apache reverse proxy
• Jenkins with NGINX reverse proxy

Combine the information from the various wiki pages into those two pages and test the content of those two pages deeply for accuracy. I'm not an NGINX expert or an Apache expert. I assume there are experts in both those within the Jenkins community (thinking of you @dduportal ). We would ask them to review the pull requests to create those two pages.

[dduportal]

Sure @MarkEWaite , I would be happy to help by contributing (any of writing, testing, reviewing) !

I'm currently reading the migration documentation to get on the page first :)

Related Wiki Pages to migrate

Some other pages in the current wiki related to this "Jenkins behind a reverse-proxy" topic:

• https://wiki.jenkins.io/display/JENKINS/Running+Jenkins+behind+Apache
• https://wiki.jenkins.io/display/JENKINS/Running+Jenkins+on+Port+80+or+443+using+iptables

Topic to highlight in the new doc page

These topics are user oriented and should guide end users (persona: Jenkins admin) whatever reverse proxy solution is used:

• Expose Jenkins to public ports (hostname and port mapping public <-> topic in relation with how Jenkins generates its pages, links and the $JENKINS_URL configuration item)
• HTTP+TLS with Jenkins:
  • Outside Jenkins (TLS termination at reverse-proxy level)
  • Inside Jenkins (End to end encryption with a reverse proxy, either with TLS passtrough or with 2 level termination)
• Exposing Agent protocol:
  • JNLPv4 (TCP reverse-proxying )
  • Websockets (HTTP reverse-proxying)
• Loadbalancing:
  • Healthcheck for Jenkins master ("how to check if Jenkins is alive to decide sending traffic to it")
  • State clearly the "no horizontal scaling of the Jenkins master" for newcomers not aware of the "stateful" context
• Authentication: passing HTTP headers to Jenkins in the context of a reverse proxy, to ensure any authN realm works (Github, SAML, LDAP, oAUTH, etc.) when redirections happen

Food for Thought

Some food for thought here (that might or might not be integrated):

• Proposal of other integrations (as they come of a lot):
  • Jenkins with HAProxy
  • Jenkins with Traefik

Let me know what is useful in these, and where should I put my effort?

[MarkEWaite]

Let me know what is useful in these, and where should I put my effort?

That is a wonderful outline! I copied it into the description as a much better starting point than my one sentence entry. I'd love to have the information that you described in the outline as part of a page in the Jenkins documentation.

I think it would be a new page in "System Administration". It could be called "Accessing Jenkins" or "Reverse Proxy Configuration for Jenkins".

I assume most audiences will want to read the information about their specific reverse proxy (Apache, NGINX, HAProxy, Traefik). Would we create an adoc file which contains the common portions then insert that into a page for each of the specific reverse proxies, with the information for the specific proxy in that page? In other words, would readers be better served by (each top level bullet represents a page):

• Reverse Proxy Configuration with Apache
• Reverse Proxy Configuration with NGINX
• Reverse Proxy Configuration with HAProxy
• Reverse Proxy Configuration with Traefik

or would be they be better served by:

• Reverse Proxy Configuration with Jenkins
  • General Guidelines
  • Apache
  • NGINX
  • HAProxy
  • Traefik

[timja]

Reverse Proxy Configuration with Traefik

When we deployed this we just turned it on and did nothing and it worked, interested to know what content would be put here.

I think a how-to guide for each technology would make most sense but depends on how much content there is, and what level it's at

[MarkEWaite]

@zaycodes has expressed interest in working on this issue. @dduportal is one of the experts that can act as a consultant and guide on the issue and how best to present the information on the jenkins.io site. @dduportal provided a good outline in his comment.

@zaycodes would that work for you?

[dduportal]

Hi @MarkEWaite !

About the outline for this topic, my vote is on: "single page" titled Reverse Proxy Configuration with Jenkins with the following table of content (bullets in the single page):

• General Guidelines
• Configuration Examples:
  • Apache
  • NGINX
  • HAProxy
  • Traefik

I'm totally OK to guide and help, even pairing with @zaycodes if it is ok for y'all ?

[dduportal]

Hi @timja !

When we deployed this we just turned it on and did nothing and it worked, interested to know what content would be put here.
Yes, same here. However, "stating the obvious" is still a good call to confirm explictly that it is expected to work.
Also, some topics could be pointed with simple examples and pointers to documentations (not only for Traefik) now or later. Such as:

• Healthchecks on Jenkins (e.g. how to avoid sending traffic to Jenkins when it is not ready)
• Terminating TLS for Jenkins or TLS pass trough
• JNLP port management

I think a how-to guide for each technology would make most sense but depends on how much content there is, and what level it's at

On this we agree. As the content to migrate is still "lightweight", my proposal is to start simple with a single page. Once the content will start to "weight", the question of splitting can be done at this time.
In order to make the reading experience better, we can use some web trickeries as foldables code snippets for instance.

WDYT ?

[timja]

Sounds good!

[MarkEWaite]

I'm totally OK to guide and help, even pairing with @zaycodes if it is ok for y'all ?

Yes @dduportal , that would be great. We'd love to have your help and your experience on this section. I love the structure you've proposed and think it sounds great.

[zaycodes]

Hello @dduportal, I'll be happy if you can guide me on working on this issue. How do I get started?

[dduportal]

@hi @zaycodes ! Yes I would happy to guide and mentor you in this issue.

In the context of the hackfest, it could be great for you to start by watching the recording of yesterday's session about doc migration here: https://www.youtube.com/watch?v=KB-NPlRvLoY (and slides here https://docs.google.com/presentation/d/1fiVoDFrSNTOHsHT4cIqyOIBKYXG0q5zVn_XPue_Khkw/edit#slide=id.g8061b508ca_0_149 ), unless you already are at ease with the process or if you were attending it already.

To get started, as outlined in the session, would be for you to:

• Fork the github repository of the documentation under your own account
• Initiate a new branch, in your fork, named after the topic ("migrating-reverse-proxy-doc") or the issue id ("3204") or even both
• Create the empty page (title only, check the other pages to see the minimum content) in the right directory (https://github.com/jenkins-infra/jenkins.io/tree/master/content/doc/book/system-administration) and add it to the the _chapter.yml sections
• Use the commande make run to generate a local copy and a local server (ref. https://github.com/jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc#make-targets)
• Start writing the content and check the result on the local server
• Once you feel like you're ready to share, push the changes to your branch, and open a Pull Request, eventually in "Draft" mode (check the green drop down button when opening the PR for this).

=> These instructions might be not enough, or might not be clear, do NOT hesitate to ask for help, clarification or anything!

You might want to join the community "gitter" discussion space for documentation at https://gitter.im/jenkinsci/docs.
It allows synchronous communication in the form of IM and sharing our work with the community (it's a channel: there is no 1:1 possibility, which aims to create both a sharing and safe place to communicat synchronously), while github can be used for asynchronously communication.

I'll try to be available as much as possible to help in any form you feel is required: pairing session with shared desktop, "office hours" session in the hackfest event (ref. https://gitter.im/jenkinsci/hackfest), message review in this issue, PR review, even in early stage.

Do as it pleases you in term of code and tries: do not fear trying stuff and asking for help. The goal is to contribute as a community and feel good about this!

[dduportal]

Hello @MarkEWaite , I found a few other wiki pages related to the "reverse proxy" topics, that are not tracked under any issues here. I'm listing these pages here, please let me know if we need to create one issue for each page, or add the pages in any tracking process?

These 3 pages have content that is worth migrating from my point of view:

• Jenkins behind HAProxy: https://wiki.jenkins.io/display/JENKINS/Running+Jenkins+behind+HAProxy
• Jenkins behind Squid: https://wiki.jenkins.io/display/JENKINS/Running+Jenkins+behind+Squid
• Jenkins behind IIS: https://wiki.jenkins.io/display/JENKINS/Running+Jenkins+behind+IIS

[MarkEWaite]

Let me know if we need to create one issue for each page, or add the pages in any tracking process?

No, this issue is enough to track all of them. Thanks for gathering those. I've updated my tracking spreadsheet to include those pages as well.

[MarkEWaite]

@dduportal don't forget to note your contribution to the Hackfest in the tracking repository by submitting a "contributor tracking issue" that notes you are helping on this issue.

[dduportal]

@MarkEWaite sure, thank for the reminder!
jenkinsci/ui-ux-hackfest-2020#189