Deskpro has to handle HTTP web requests from your users. For most cases, we recommend running Deskpro behind a reverse proxy where you can perform tasks like SSL termination or load balancing. But you can also expose a Deskpro container directly to users.

Use the built-in web server

If you wish to have users connect directly to th built-in web server, you can just expose port 80 through your host (or port 443 if you enable HTTPS). This is the default way to run the container.

For example, if you started a container like this:

docker run \
  --env-file config.env \
  --name deskpro \
  -p 80:80 \
  deskpro/deskpro-product:$DPVERSION-onprem
 copy

... then you could access Deskpro in a browser through http://127.0.0.1/ from that server itself. If your host server is exposed to the internet, then you could access it via the public IP address in the same way.

Using mapped ports

If you are mapping port (i.e. the port/protocol in your browser URL bar is not 80/443) then you need to set a couple other options so the system knows what "real" ports/protocols to present to the user.

E.g. if you ran Deskpro like this:

docker run --env-file "config.env" \
  -p 8080:80 \
  -p 8443:443 \
  deskpro/deskpro-product:$DPVERSION-onprem
 copy

... then you would have mapped port 8080/8443 on the host to the internal web server on ports 80/443 inside the container. This would enable you to visit http://127.0.0.1:8080, but Deskpro in the container still sees it as a request through port 80.

To make this work properly, you must tell Deskpro about the "real" port the user is requesting by specifying two env vars:

1. HTTP_USER_SET_HTTP_PORT=8080 -- specifies that the host is using port 8080 for HTTP requests

2. HTTP_USER_SET_HTTPS_PORT=8443 -- specifies that the host is using port 8443 for HTTPS requests

So that same command above would become:

docker run --env-file "config.env" \
  -p 8080:80 \
  -p 8443:443 \
  -e HTTP_USER_SET_HTTP_PORT=8080 \
  -e HTTP_USER_SET_HTTPS_PORT=8443 \
  deskpro/deskpro-product:$DPVERSION-onprem
 copy

Using a reverse proxy

When using a reverse proxy, you need a little bit of configuration to ensure that Deskpro "knows" about the original users request. Typically this is done by your proxy setting certain HTTP headers on the request. To enable Deskpro to read these headers, you have to explicitly set them.

Here are some common examples:

# Real IP address of the user
HTTP_USER_REAL_IP_HEADER="X-Forwarded-For"
HTTP_USER_REAL_IP_HEADER="True-Client-IP"
HTTP_USER_REAL_IP_HEADER="X-Real-IP"

# Real connecting Host (domain name)
# Some proxies may send this as host:port
# This may not be necessary if your proxy is sending
# a proper Host header already
HTTP_USER_REAL_HOST_HEADER="X-Forwarded-Host"

# Real protocol that the user used (http or https)
HTTP_USER_REAL_PROTO_HEADER="X-Forwarded-Proto"

# Real port that the user used. May not be necessary
# if your proxy is sending a host that includes a port number.
HTTP_USER_REAL_PORT_HEADER="X-Forwarded-Port"
 copy

If any of these values are static, you may set them as static values instead:

# The domain name / host name that should always be used
# (i.e. instead of HTTP_USER_REAL_HOST_HEADER)
HTTP_SERVE_HOST="support.example.com"

# Set the protocol and port for requests
# (i.e. instead of HTTP_USER_REAL_PROTO_HEADER and HTTP_USER_REAL_PORT_HEADER)
HTTP_USER_SET_HTTP_PROTO="http"
HTTP_USER_SET_HTTP_PORT="80"
HTTP_USER_SET_HTTPS_PROTO="https"
HTTP_USER_REAL_HTTPS_PORT="443"
 copy

Proxy Protocol

If your proxy supports the proxy protocol, then you may use ports 9080/9443 for http/https.

The users IP address and port are always set when using the proxy protocol. That means you don't need to set HTTP_USER_REAL_IP_HEADER or HTTP_USER_REAL_PORT_HEADER yourself. However, you may still need to set HTTP_USER_REAL_PROTO_HEADER and HTTP_USER_REAL_HOST_HEADER if those values aren't default (e.g. if you are using ports other than 80/443).

Important: Security when using a proxy

When you enable any headers such as X-Forwarded-*, Deskpro will always trust them implicitly. But HTTP headers are trivial to spoof, and there are certain security vulnerabilities that could be exploited if a malicious user were able to send specially creafted HTTP requests directly to Deskpro when these headers are enabled.

So there are two "rules" you need to keep in mind when Deskpro sits behind a proxy:

1. Ensure ONLY the proxy can send traffic to Deskpro (e.g. using a firewall)

2. Ensure your proxy server is setting all headers you defined (i.e. ensure there is no arbitrary header pass-through)

Using Cloudflare

Cloudflare behaves a little like a normal reverse proxy. You would use configuration like this:

HTTP_USER_REAL_IP_HEADER="CF-Connecting-IP"
HTTP_USER_REAL_PROTO_HEADER="X-Forwarded-Proto"
 copy

Cloudflare will send requests through with the same Host, so mapping that isn't necessary. Depending on how you've configured Cloudflare, it may send HTTPS traffic back to your server over HTTP, hence the need to map the protocol with the X-Forwarded-Proto header.

Enable HTTPS (port 443)

The internal web server does not listen for HTTPS requests (port 443) by default. To enable listening on port 443 for HTTPS, you need to supply a valid SSL certificate:

• Mount your certificate at (pem format): /deskpro/ssl/certs/deskpro-https.crt

• Mount your (unencrypted) key at: /deskpro/ssl/private/deskpro-https.key

Alternatively, you can use the built-in pre-generated self-signed testing certificate by specifying the environmental variable HTTP_USE_TESTING_CERTIFICATE=true.

Here's an example running the default server with custom certificate files mounted:

# e.g. imagine if you have a my_cert.crt and my_cert.key in the current directory:

docker run --env-file "config.env" \
  -v $(pwd)/my_cert.crt:/deskpro/ssl/certs/deskpro-https.crt
  -v $(pwd)/my_cert.key:`/deskpro/ssl/private/deskpro-https.key
  deskpro/deskpro-product:$DPVERSION-onprem
 copy