WAIIDE_TECHNICAL_BLUEPRINT_V1

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

CORE_IDENTITY

container:calliopeai/waiide:latest|purpose:WAIIDE-server-jupyterhub-integration|modes:jupyterhub,standalone

ARCHITECTURE_MATRIX

entrypoint:/usr/local/bin/entrypoint-jupyterhub.sh
├─envdetect:JUPYTERHUB_SERVICE_PREFIX|JUPYTERHUB_USER|JUPYTERHUB_API_TOKEN
├─permfix:root→uid1000,gid100,home:/home/{JUPYTERHUB_USER}
├─mode_jupyterhub:
│ ├─WAIIDE:localhost:8081,args:--host=127.0.0.1,--without-connection-token
│ ├─jupyterhub-singleuser:0.0.0.0:8080,--ServerApp.default_url=/proxy/8081/
│ └─jupyter-server-proxy:route:/proxy/8081/→localhost:8081,strip_prefix:auto
└─mode_standalone:
  ├─api_server:0.0.0.0:8080,python3:/usr/local/bin/api_server.py
  └─vscode_autostart:if_not_running,port:8081

PORTS

primary:8080|vscode_internal:8081|expose:8080,8081|bind:0.0.0.0:8080,127.0.0.1:8081

ENV_VARS_CRITICAL

JUPYTERHUB_SERVICE_PREFIX=/user/{username}/[{servername}/]
JUPYTERHUB_USER={username}
JUPYTERHUB_API_TOKEN={oauth_token}
JUPYTERHUB_SERVER_NAME={servername_if_named}
PORT=8080
USE_ALL_COMPONENTS=true

OAUTH_FIXES

oauth_named_server_fix.py:intercept_redirect,fix:/user/alice/waiide/hub/api/oauth2→/hub/api/oauth2 jupyter_scope_fix.py:patch_scopes,add:access:servers!server={username}/{servername} jupyter_server_config.py:PermissiveIdentityProvider,allow_any_authenticated_jupyterhub_user

API_ENDPOINTS

GET /api→{status,user,server,version,mode,service_prefix,services,endpoints}
GET /api/services→{services:{WAIIDE,api},total_services,architecture}
GET /api/status→{status,user,server,version,note}
GET /api/*→basic_status
*→proxy_to_vscode(strip_prefix,rewrite_content)

URL_REWRITING

request:strip_prefix(JUPYTERHUB_SERVICE_PREFIX) response:rewrite_patterns[html:src,href,action|js:fetch,XMLHttpRequest,WebSocket|css:url()|imports]

REQUEST_FLOW

jupyterhub:/user/{username}/path→container:8080→jupyterhub-singleuser→jupyter-server-proxy→strip:/path→WAIIDE:8081 standalone:/path→container:8080→api_server→proxy:/path→WAIIDE:8081

WEBSOCKET

detect:Upgrade:websocket→establish_backend_connection→bidirectional_forward

FILE_STRUCTURE

/home/{username}/
├─workspace/
├─.WAIIDE-server/data/Machine/settings.json[theme:Pergamon Blue]
├─.jupyter/jupyter_server_config.py
└─.local/share/jupyter/runtime/

DOCKERFILE_KEY_STEPS

FROM mcr.microsoft.com/devcontainers/typescript-node:22-bookworm
# Note: WAIIDE requires Node.js v22.15.1 or later
RUN pip3 install jupyter-server-proxy[standalone] jupyterhub
USER root
EXPOSE 8080 8081
ENTRYPOINT ["/bin/bash","-c"]
CMD ["exec /usr/local/bin/entrypoint-jupyterhub.sh"]

SPAWNER_CONFIG_MINIMAL

c.DockerSpawner.image='calliopeai/waiide:latest'
c.DockerSpawner.network_name='jupyterhub-network'
c.DockerSpawner.volumes={'jupyterhub-user-{username}':'/home/{username}'}
c.DockerSpawner.cmd=''
c.Spawner.default_url='/proxy/8081/'

NAMED_SERVER_ISSUE

problem:JUPYTERHUB_OAUTH_ACCESS_SCOPES missing servername container_fix:implemented(oauth_fixes) hub_fix:c.JupyterHub.allow_named_servers=False|patch_spawner_get_env

SERVICE_DETECTION_LOGIC

if [ -n "$JUPYTERHUB_SERVICE_PREFIX" ]||[ -n "$JUPYTERHUB_USER" ]||[ -n "$JUPYTERHUB_API_TOKEN" ];then
  MODE=jupyterhub
else
  MODE=standalone
fi

BUILD_REQUIREMENTS

node_version:v22.15.1+|reason:vscode_preinstall_check|base_image:devcontainers/typescript-node:22

PERFORMANCE

startup:10-15s|memory:~1GB|cpu:low_idle|network_overhead:<5ms

DEBUG_COMMANDS

docker exec {container} env|grep JUPYTER
curl http://localhost:8080/api/services
docker logs {container}

THEME_DEFAULT

workbench.colorTheme:“Pergamon Blue”|location:assets/server-settings.json|copied:/home/{username}/.WAIIDE-server/data/Machine/settings.json