Document a high level technical overview on how this project work

[consideRatio]

I think all projects benefit greatly from a technical overview as that allows anyone to better onboard and for example debug issues or contribute to maintenance in various ways.

Here are some notes that I've distilled from learning how this project works in order to help me debug and maintain things in this project. They should absolutely be refined further, but this is similar to the level of overview I think we should provide in the README, for example under a "How it works" heading like for jupyterhub-idle-culler.

jupyter_server_proxy server entrypoints

• /desktop-websockify/

  Requests here are listened to by websockify. It terminates websocket traffic and proxies data to a VNC server. setup_websockify returns a command to start websockify, that in turn wraps startup of a vncserver, that in turn wraps startup of a desktop session via a passed xstartup script. When websockify wraps the startup of a vncserver, it intercepts the socket bind request to hijack listening on that port, and instead lets the vncserver listen to some other port it then will forward traffic to.

  The purpose of websockify is to bridge websocket traffic into a normal socket traffic.

  At the most basic level, websockify just translates WebSockets traffic to normal socket traffic. Websockify accepts the WebSockets handshake, parses it, and then begins forwarding traffic between the client and the target in both directions.

  The associated JupyterLab launcher entry redirects users to /desktop/, which in turn provides an index.html referencing a viewer.js that interacts via websockets with /desktop-websockify/.

  The way jupyter-server-proxy proxies communication can be either via a unix socket or via a TCP port. Only TigerVNC supports listening to unix sockets though.

bundled file

• xstartup is a simple sh executable that starts desktop stuff, it needs
  to be referenced when launching the VNC server. ~/.vnc/xstartup can be
  provided as an alternative

jupyter_server extension

• serves /desktop, redirects to /desktop/
• serves /desktop/static/
  • cliboard.svg
  • jupyter-logo.svg
  • dist/viewer.js (built, depends on novnc)
  • dist/index.css (built)
• serves /desktop/
  • index.html (rendered from index.html template with a base_url)

[manics]

websockify also intercepts the VNCserver's TCP socket bind request (e.g. to 5901), transparently changes the internal library call so that the VNCserver binds to <random-port>, and websockify listens on the original specified port (5901) instead. See the Wrap a Program section of https://pypi.org/project/websockify/#description

[consideRatio]

Ah, but we can't make use of that right? We need to specify it so that jsp proxies to what websockify exposes right? I errored without #99 in turbovnc listening to a random TCP port

[ashwaqrehman]

Hi @consideRatio,
I am seeking clarification regarding the usage and capabilities of the Jupyter Remote Desktop Proxy, as I found the README lacking in providing an overview of its use cases and functionalities.
Our current setup involves a JupyterHub server and five Jupyter Notebook servers. The JupyterHub server serves as a proxy, directing users to their respective Jupyter Notebook servers based on their user group.
Now, we have a specific requirement: we want users to access every notebook session through a VNC session to ensure the security of our files and prevent unauthorized downloading and copying of contents.

Here are the questions I need clarification on:

1. Can we utilize the Jupyter Remote Desktop Proxy to proxy our JupyterHub in a way that enables opening a notebook session within a VNC desktop session?
2. If such proxying is possible, I'd like to understand whether the VNC sessions opened will be dynamic or static. For instance, if user A logs into the JupyterHub and user B also logs in, will they each receive separate VNC desktop sessions? It's crucial that each user has their own isolated desktop session, ensuring changes made in one user's Jupyter Notebook do not reflect in another user's desktop session.