Below are some diagrams of OnDemand’s architecture:

  1. Overview is a high level visual generated from Powerpoint
  2. System context and Container context diagrams below follow the C4 model for software diagrams, are more technically detailed and are built using
  3. Request flow diagram is a sequence diagram built using plantuml


  1. Apache is the server front end, running as the Apache user, and accepting all requests from users and serves four primary functions
    1. Authenticates user
    2. Starts Per-User NGINX processes (PUNs)
    3. Reverse proxies each user to her PUN via Unix domain sockets
    4. Reverse proxies to interactive apps running on compute nodes (RStudio, Jupyter, VNC desktop) via TCP sockets
  2. The Per-User NGINX serves web apps in Ruby and NodeJS and is how users submit jobs and start interactive apps

System context

Users use OnDemand to interact with their HPC resources through a web browser. At the highest level, this is what the OnDemand system does. OnDemand is the system that enables that interaction.


All the gray components are specific to a given site and outside the OnDemand system.

Container context

In the C4 nomenclature, ‘containers’ are one level below the system context. This is not to be confused with Linux containers via cgroups and namespaces (i.e. Docker or Singularity or OCI containers).

It’s important to note in this diagram that the frontend proxy is the only component that is shared for all clients. The system will create Per User Nginx processes (referred to as PUNs throughout the documentation). So what’s diagrammed here in the outer light blue box is replicated for every client accessing the system.

  • Everything contained in the dotted line is a part of the OnDemand system.
  • Everything outside of it in gray is site specific components.

Request Flow

This is the request flow through the OnDemand system. A user initiates a request through a browser and this illustrates how that request propogates through the system to a particular application (including the dashboard).


title Request flow through the OnDemand system
autonumber "<b>[0]"

participant User
participant "Apache Httpd"
participant Authentication
participant LuaScripts
participant Nginx
participant "Passenger/App"

User -[#red]> "Apache Httpd": request

activate "Apache Httpd"

"Apache Httpd" -[#red]> Authentication: Authenticate request
activate Authentication
Authentication -[#red]> "Apache Httpd" : Authenticate response
deactivate Authentication

"Apache Httpd" -[#green]> LuaScripts: Lua Hooks
activate LuaScripts
LuaScripts -[#green]> LuaScripts: map user
alt socket doesn't exist
  LuaScripts -[#green]> Nginx: Start nginx as $user
end group
LuaScripts -[#green]> LuaScripts: modify request and proxy connection

"Apache Httpd" -[#blue]> Nginx: proxy request
deactivate LuaScripts
Nginx -[#blue]> "Passenger/App": proxy request
"Passenger/App" -[#blue]> Nginx: response
Nginx -[#blue]> "Apache Httpd": response
"Apache Httpd" -[#red]> User: response
deactivate "Apache Httpd"

legend left
|= |= Protocol |
|<back:red>   </back>| https over tcp |
|<back:green>   </back>| commands |
|<back:blue>   </back>| http over unix socket |