ECS Instance Names for WAIIDE

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

Overview

WAIIDE supports receiving instance names from ECS spawners to create clean, unique URLs for each container instance.

How It Works

When the ECS spawner creates a WAIIDE container, it should set the following environment variables:

# Required: The server/instance name
JUPYTERHUB_SERVER_NAME=lmata-waiide-abc123

# Required: The username
JUPYTERHUB_USER=lmata

# Required: The service prefix (full path)
JUPYTERHUB_SERVICE_PREFIX=/user/lmata/lmata-waiide-abc123/

URL Structure

With these environment variables set, WAIIDE will:

1. Serve WAIIDE at the root: https://hub.example.com/user/lmata/lmata-waiide-abc123/
2. Handle OAuth correctly: Using the instance name in callback URLs
3. Display instance info: Show the instance name in logs and API responses

ECS Spawner Configuration

Your ECS spawner should:

1. Generate unique instance names (e.g., username-service-hash)
2. Pass the instance name as JUPYTERHUB_SERVER_NAME
3. Ensure the JUPYTERHUB_SERVICE_PREFIX matches the full path

Example ECS task definition environment:

{
  "environment": [
    {
      "name": "JUPYTERHUB_SERVER_NAME",
      "value": "lmata-waiide-abc123"
    },
    {
      "name": "JUPYTERHUB_USER", 
      "value": "lmata"
    },
    {
      "name": "JUPYTERHUB_SERVICE_PREFIX",
      "value": "/user/lmata/lmata-waiide-abc123/"
    },
    {
      "name": "JUPYTERHUB_API_TOKEN",
      "value": "<oauth-token>"
    },
    {
      "name": "JUPYTERHUB_API_URL",
      "value": "http://hub:8081/hub/api"
    }
  ]
}

Benefits

• Clean URLs: Users access WAIIDE directly at /user/lmata/lmata-waiide-abc123/
• No path confusion: No /WAIIDE/ or /proxy/8081/ paths visible
• Multiple instances: Each instance has a unique, identifiable URL
• Consistent naming: Container names match JupyterHub server names

Verification

To verify the instance name is working:

1. Check the container logs:

   Running as named server: lmata-waiide-abc123 for user: lmata

2. Access the API endpoint:

   curl https://hub.example.com/user/lmata/lmata-waiide-abc123/api

   Response should include:

   {
     "server": "waiide",
     "user": "lmata",
     "service_prefix": "/user/lmata/lmata-waiide-abc123/",
     "mode": "jupyterhub"
   }

3. WAIIDE should be accessible at the root URL without any additional paths.