In situations where you want a user friendly URL, different public ports, or to terminate SSL connections before they reach Jenkins, you may find it useful to run Jenkins (or the servlet container that Jenkins runs in) behind HAProxy. This document discusses some of the approaches for doing this.

Plain HTTP

Using HAProxy 1.7.9, here is an example HAProxy.cfg to proxy over plain HTTP:

# If you already have an haproxy.cfg file, you can probably leave the
# global and defaults section as-is, but you might need to increase the 
# timeouts so that long-running CLI commands will work.
global 
    maxconn 4096 
    log 127.0.0.1 local0 debug

defaults
   log global
   option httplog
   option dontlognull
   option forwardfor
   maxconn 20
   timeout connect 5s
   timeout client 60s
   timeout server 60s

frontend http-in
   bind *:80
   mode http
   acl prefixed-with-jenkins  path_beg /jenkins/
   acl host-is-jenkins-example   hdr(host) eq jenkins.example.com
   use_backend jenkins if host-is-jenkins-example prefixed-with-jenkins

backend jenkins
   server jenkins1 127.0.0.1:8080
   mode http
   reqrep ^([^\ :]*)\ /(.*) \1\ /\2
   acl response-is-redirect res.hdr(Location) -m found
   rspirep ^Location:\ (http|https)://127.0.0.1:8080/jenkins/(.*) Location:\ \1://jenkins.example.com/jenkins/\2 if response-is-redirect

This assumes Jenkins is running locally on port 8080.

This assumes that you are using the /jenkins/ context path for both the site exposed from HAProxy, and Jenkins itself. If this is not the case, you will need to adjust the configuration.

If you are experiencing the following error when attempting to run long CLI commands in Jenkins > 2.80, and Jenkins is running behind HAProxy, it is probably due to HAProxy timing out the CLI connection. You can increase the timeout client and timeout server settings as necessary so the command will complete successfully. Versions of Jenkins before 2.80 might not respect the proxy_read_timeout setting.

WARNING: null
hudson.cli.DiagnosedStreamCorruptionException
Read back: 0x00 0x00 0x00 0x1e 0x07 'Started reverse-proxy-test #68' 0x00 0x00 0x00 0x01 0x07 0x0a
Read ahead: 
Diagnosis problem:
    java.io.IOException: Premature EOF
    	at sun.net.www.http.ChunkedInputStream.readAheadBlocking(ChunkedInputStream.java:565)
    	...
	at hudson.cli.FlightRecorderInputStream.analyzeCrash(FlightRecorderInputStream.java:82)
	at hudson.cli.PlainCLIProtocol$EitherSide$Reader.run(PlainCLIProtocol.java:153)
Caused by: java.io.IOException: Premature EOF
	at sun.net.www.http.ChunkedInputStream.readAheadBlocking(ChunkedInputStream.java:565)
	...
	at java.io.DataInputStream.readInt(DataInputStream.java:387)
	at hudson.cli.PlainCLIProtocol$EitherSide$Reader.run(PlainCLIProtocol.java:111)


With SSL

Using HAProxy 1.7.9, here is an example HAProxy.cfg to connect to the proxy using SSL, terminate the SSL connection, and then talk to Jenkins using plain HTTP:

# If you already have an haproxy.cfg file, you can probably leave the
# global and defaults section as-is, but you might need to increase the 
# timeouts so that long-running CLI commands will work.
global 
    maxconn 4096 
    log 127.0.0.1 local0 debug

defaults
   log global
   option httplog
   option dontlognull
   option forwardfor
   maxconn 20
   timeout connect 5s
   timeout client 5min
   timeout server 5min
 
frontend http-in
    bind *:80
    bind *:443 ssl crt /usr/local/etc/haproxy/ssl/server.pem
    mode http
    redirect scheme https if !{ ssl_fc } # Redirect http requests to https
    use_backend jenkins if { path_beg /jenkins/ }

backend jenkins
    server jenkins1 127.0.0.1:8080
    mode http
    http-request set-header X-Forwarded-Port %[dst_port]
    http-request add-header X-Forwarded-Proto https if { ssl_fc }
    reqrep ^([^\ :]*)\ /(.*)     \1\ /\2
    acl response-is-redirect res.hdr(Location) -m found
    rspirep ^Location:\ (http)://127.0.0.1:8080/(.*)   Location:\ https://jenkins.example.com:443/\2  if response-is-redirect