content/posts/2025-03-30-jupyterlab-reverse-proxying-in-apache.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

---
slug: jupyterlab-reverse-proxying-in-apache
title: "JupyterLab Reverse Proxying in Apache"
date: "2025-03-30T22:57:18-04:00"
draft: true
---

I've been using the [SageMath][] kernel in [JupyterLab][] quite a bit
lately.  I wanted to [reverse proxy][] through an [Apache][] [vhost][]
to [JupyterLab][].  The documentation to do this is surprisingly
elusive.

Here is a working example:

```apache
<VirtualHost *:443>
  ServerName sage.example.com

  # proxy http and websocket to http://localhost:1980/
  # note: in apache 2.4.47+, use upgrade=websocket to proxy websocket
  ProxyPass "/" http://localhost:1980/ upgrade=websocket
  ProxyPassReverse "/" http://localhost:1980/ upgrade=websocket

  # preserve Host header in proxied requests
  ProxyPreserveHost on

  # ... common vhost configuration elided
</VirtualHost>
```
&nbsp;

Notes:

1. Add `upgrade=websocket` to [ProxyPass][] and [ProxyPassReverse][].
Needed to proxy [WebSocket][] connections in [Apache][] 2.4.47+.  See
the [Protocol Upgrade note][protocol-upgrade] in the [mod\_proxy
documentation][mod_proxy] for additional details.
2. Enable [ProxyPreserveHost][].  This preserves the `Host` header in
proxied requests and it is needed to prevent cryptic server-side origin
errors.

The [JupyterLab][] instance is running in a [Podman][] [container][],
like so:

```sh
podman run -d -p 1980:8888 \
  -v sage:/home/sage/work \
  --restart=on-failure \
  --name sage \
  docker.io/sagemath/sagemath sage-jupyter
```

[jupyterlab]: https://jupyter.org/
  "JupyterLab"
[apache]: https://apache.org/
  "Apache web server"
[reverse proxy]: https://en.wikipedia.org/wiki/Reverse_proxy
  "Reverse proxy (Wikipedia)"
[vhost]: https://httpd.apache.org/docs/current/vhosts/
  "Apache virtual host (apache.org)"
[protocol-upgrade]: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#wsupgrade
  "Protocol Upgrade note in mod_proxy documentation."
[proxypass]: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#proxypass
  "ProxyPass directive (apache.org)"
[proxypassreverse]: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#proxypassreverse
  "ProxyPassReverse directive (apache.org)"
[proxypreservehost]: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#proxypreservehost
  "ProxyPreserveHost directive (apache.org)"
[websocket]: https://en.wikipedia.org/wiki/WebSocket
  "WebSocket (Wikipedia)"
[sagemath]: https://sagemath.org/
  "SageMath"
[mod_proxy]: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html
  "Apache proxy module."
[mod_proxy_http]: https://httpd.apache.org/docs/2.4/mod/mod_proxy_http.html
  "Apache module to proxy HTTP requests."
[podman]: https://en.wikipedia.org/wiki/Podman
  "Podman container manager (Wikipedia)"
[container]: https://en.wikipedia.org/wiki/Containerization_(computing)
  "Operating system level virtualization (Wikipedia)"