Documentation
Waiide
🎯 Your First WAIIDE Instance

🎯 Your First WAIIDE Instance

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

This guide walks you through creating, accessing, and using your first WAIIDE instance, helping you understand the multi-instance architecture and key features.

🚀 Creating Your First Instance

1. Access JupyterHub

Navigate to your JupyterHub instance:

http://localhost:8000

2. Login

Use your configured authentication method:

  • PAM: System username/password
  • OAuth: Click your OAuth provider button

3. Start a Named Server

From the Control Panel

  1. After login, you’ll see the JupyterHub control panel
  2. Look for “Named Servers” section
  3. Click “New Server” or “Add New Server”

Choose a Server Name

Pick a descriptive name for your instance:

  • Good names: waiide-dev, project-alpha, data-analysis
  • Avoid: Special characters, spaces, or very long names

Example: Enter waiide-dev as your server name

4. Container Startup

  • JupyterHub will create a container named username-waiide-dev
  • The startup process takes 30-60 seconds
  • You’ll see a progress indicator

🌐 Accessing Your Instance

Understanding the URL Structure

Your WAIIDE instance will be accessible at:

http://localhost:8000/user/[username]/[username]-[servername]/

Example URLs:

  • User: testuser, Server: waiide-dev
  • Full URL: http://localhost:8000/user/testuser/testuser-waiide-dev/

Key URL Features

  • ✅ Clean URLs: No /WAIIDE/ or /proxy/port/ paths
  • ✅ Direct Access: WAIIDE loads immediately at the root
  • ✅ Unique Instances: Each server has its own URL namespace
  • ✅ Bookmarkable: Save and share specific instance URLs

💻 Using WAIIDE

First Look at WAIIDE

When your instance loads, you’ll see:

  • WAIIDE Interface: Full WAIIDE experience in your browser
  • CalliopeAI Branding: Custom theme and extensions
  • File Explorer: Access to your workspace
  • Terminal: Integrated terminal access

Key Features to Try

1. Open a File 

# WAIIDE will start in /home/calliope
# Try creating a new file
touch hello-world.py

2. Use the Terminal

  • Access: View > Terminal or `Ctrl+``
  • Full shell: Complete Linux environment
  • Package installation: pip, npm, apt available

3. Install Extensions

  • Extension panel: Click the extensions icon (squares)
  • Search and install: WAIIDE marketplace access
  • Persistence: Extensions persist across container restarts

4. CalliopeAI Features

  • Pergamon Theme: Beautiful dark/light themes included
  • CalliopeAI Agent: AI-powered development assistance (if configured)

🔄 Managing Multiple Instances

Creating Additional Instances

  1. Return to JupyterHub control panel: /hub/home
  2. Create another named server (e.g., data-science)
  3. Access at: /user/testuser/testuser-data-science/

Instance Isolation

  • Separate Containers: Each instance runs independently
  • Isolated Filesystems: No shared data between instances by default
  • Independent State: Extensions, settings, and processes are separate

Switching Between Instances

  • Control Panel: /hub/home shows all your instances
  • Direct URLs: Bookmark specific instances
  • Instance List: See running/stopped instances

📊 Monitoring Your Instance

Container Status 

# Check running containers
docker ps | grep testuser

# Check container resources
docker stats testuser-waiide-dev

JupyterHub Admin Panel

If you’re an admin user:

  1. Go to /hub/admin
  2. View all user instances
  3. Stop/start instances for users

🛠️ Customizing Your Instance

Environment Variables

Customize your instance behavior through JupyterHub configuration:

# In jupyterhub_config.py
c.DockerSpawner.environment = {
    'USE_ALL_COMPONENTS': 'true',
    'LOG_LEVEL': 'DEBUG',
    'WAIIDE_THEME': 'pergamon-dark',
    'CUSTOM_SETTING': 'value'
}

Volume Mounts

Persist data between container restarts:

# In jupyterhub_config.py
c.DockerSpawner.volumes = {
    '/home/{username}': '/home/calliope',  # Persist home directory
    '/shared': '/shared'  # Shared volume across instances
}

Resource Limits

Control instance resource usage:

# In jupyterhub_config.py
c.DockerSpawner.mem_limit = '4G'  # 4GB RAM limit
c.DockerSpawner.cpu_limit = 2     # 2 CPU cores

🔍 Understanding Instance Lifecycle

Instance States

  • Starting: Container is being created and initialized
  • Running: Instance is active and accessible
  • Stopped: Container is stopped but not removed
  • Failed: Startup failed - check logs

Starting an Instance 

JupyterHub → DockerSpawner → Container Creation → Service Start → WAIIDE Ready

Stopping an Instance

  • From Control Panel: Click “Stop” next to instance name
  • Automatic: Instances may stop after inactivity (configurable)
  • Manual: docker stop testuser-waiide-dev

Data Persistence

  • With volumes: Data persists across restarts
  • Without volumes: Data is lost when container is removed
  • Best practice: Always configure volume mounts for important data

🚨 Troubleshooting First Instance Issues

Instance Won’t Start 

# Check JupyterHub logs
sudo journalctl -u jupyterhub -f

# Check container logs
docker logs testuser-waiide-dev

# Check if image exists
docker images | grep waiide

Can’t Access WAIIDE

  1. Check URL: Ensure you’re using the correct URL format
  2. Check Container: docker ps | grep testuser
  3. Check Logs: docker logs testuser-waiide-dev
  4. Try Refresh: Sometimes WAIIDE needs a browser refresh

Performance Issues 

# Check system resources
htop

# Check container resources
docker stats

# Check memory usage
free -h

Authentication Problems

  1. Clear browser cache: Shift+Ctrl+R
  2. Check cookies: Clear JupyterHub cookies
  3. Re-login: Log out and back in to JupyterHub

✅ First Instance Checklist

After completing this guide, verify:

  • Instance created successfully
  • Can access WAIIDE at clean URL
  • Terminal works within WAIIDE
  • Can create and edit files
  • Extensions can be installed
  • Multiple instances can be created
  • Can switch between instances

🎯 Common Workflows

Development Workflow

  1. Create instance for your project (myproject-dev)
  2. Clone repository in WAIIDE terminal
  3. Install dependencies (pip install -r requirements.txt)
  4. WAIIDE and test using WAIIDE features
  5. Stop instance when done (data persists with volumes)

Data Science Workflow

  1. Create instance (data-analysis)
  2. Install packages (pip install pandas numpy jupyter)
  3. Upload data via WAIIDE file explorer
  4. Create notebooks and analysis scripts
  5. Export results when complete

Multiple Project Workflow

  1. Instance per project: project-a, project-b, project-c
  2. Switch as needed: Use JupyterHub control panel
  3. Isolated environments: Each project has separate dependencies
  4. Resource management: Stop unused instances

➡️ Next Steps

Congratulations! You’ve successfully created and used your first WAIIDE instance.

Continue Learning

Advanced Topics

📞 Need Help?

🎉 Happy coding with your new WAIIDE instance!

⚙️ Basic WAIIDE Setup📋 WAIIDE Reference Documentation