Your First Training Session

This guide walks you through running a complete training session with Teabar. You’ll create a GitLab CI/CD workshop environment for 10 participants, with activity tracking, isolated workspaces, and automatic cleanup.

Tip

Already ran the Quick Start? This guide goes deeper into training-specific features like participant management, activity tracking, and cost optimization.

What You’ll Build

By the end of this guide, you’ll have:

Component	Description
GitLab Instance	Full GitLab server with CI/CD enabled
CI/CD Runners	2 dedicated runners for pipeline execution
Participant Workspaces	10 isolated namespaces with pre-configured access
Activity Tracking	Real-time monitoring of participant progress
Auto-Cleanup	Environment automatically destroys after 8 hours

Estimated cost: $15-20 for an 8-hour session

Prerequisites

Before starting, ensure you have:

teactl installed and authenticated
A Teabar account (Pro plan recommended for participant features)
Participant email addresses (optional, for direct invitations)

Understanding the Training Flow

┌──────────────────────────────────────────────────────────────────┐
│                        Training Session Flow                      │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│   1. CREATE          2. INVITE           3. MONITOR              │
│   ┌─────────┐       ┌─────────┐        ┌─────────┐              │
│   │Blueprint│──────▶│  Send   │───────▶│  Track  │              │
│   │  + Env  │       │ Links   │        │Activity │              │
│   └─────────┘       └─────────┘        └─────────┘              │
│        │                                     │                    │
│        │         4. EXTEND/CHECKPOINT        │                    │
│        │            ┌─────────┐              │                    │
│        └───────────▶│  Manage │◀─────────────┘                    │
│                     │ Session │                                   │
│                     └─────────┘                                   │
│                          │                                        │
│                          ▼                                        │
│                    5. CLEANUP                                     │
│                    ┌─────────┐                                    │
│                    │ Destroy │                                    │
│                    │   Env   │                                    │
│                    └─────────┘                                    │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Step 1: Create a Blueprint

Blueprints define your training environment. Create a file called cicd-workshop.yaml:

# cicd-workshop.yaml
apiVersion: teabar.dev/v1
kind: Blueprint
metadata:
  name: cicd-workshop
  description: GitLab CI/CD hands-on training environment
  labels:
    category: devops
    difficulty: beginner
    duration: 8h

spec:
  # Environment lifecycle
  ttl: 8h # Auto-destroy after 8 hours

  # Infrastructure provider
  provider: hetzner # Cost-effective European cloud
  region: eu-central # Frankfurt region

  # Core components
  components:
    # GitLab server
    - name: gitlab
      type: gitlab
      version: '16.8'
      config:
        # Pre-create repositories for exercises
        repositories:
          - name: hello-ci
            template: teabar/gitlab-ci-basics
          - name: docker-build
            template: teabar/docker-pipeline
        # Enable CI/CD features
        features:
          - container-registry
          - ci-cd
          - auto-devops
      resources:
        cpu: 4
        memory: 8Gi
        storage: 50Gi

    # CI/CD runners for pipeline execution
    - name: runner
      type: gitlab-runner
      count: 2 # Two runners for parallel jobs
      config:
        executor: docker
        concurrent: 4 # Jobs per runner
        docker:
          image: docker:24.0
          privileged: true # Required for docker-in-docker
      resources:
        cpu: 2
        memory: 4Gi
        storage: 20Gi

  # Participant configuration
  participants:
    count: 10 # Maximum participants
    isolation: namespace # Each gets their own namespace

    # Resources per participant
    resources:
      cpu: 1
      memory: 2Gi
      storage: 10Gi

    # Pre-configured access
    access:
      - gitlab: developer # GitLab developer role
      - kubernetes: edit # K8s edit permissions

    # Workspace initialization
    init:
      # Clone exercise repos automatically
      - git clone https://gitlab.${ENV_DOMAIN}/exercises/hello-ci.git
      - git clone https://gitlab.${ENV_DOMAIN}/exercises/docker-build.git

  # Activity tracking for instructor visibility
  tracking:
    enabled: true
    events:
      - git-push # Track code pushes
      - git-clone # Track repo clones
      - pipeline-run # Track CI/CD runs
      - pipeline-status # Track pass/fail
      - shell-command # Track terminal activity

    # Progress milestones
    milestones:
      - name: 'First Push'
        event: git-push
        description: 'Participant pushed their first commit'
      - name: 'Pipeline Success'
        event: pipeline-status
        condition: status == "success"
        description: 'First successful pipeline run'

  # Networking
  networking:
    # Expose GitLab externally
    ingress:
      - host: gitlab.${ENV_NAME}.env.teabar.dev
        service: gitlab
        port: 80

    # Internal communication
    dns:
      enabled: true
      domain: ${ENV_NAME}.local

  # Hooks for customization
  hooks:
    postCreate: |
      #!/bin/bash
      echo "Workshop environment ready!"
      echo "GitLab URL: https://gitlab.${ENV_NAME}.env.teabar.dev"

    preDestroy: |
      #!/bin/bash
      # Export participant activity logs
      teactl env export-activity ${ENV_NAME} --output /tmp/activity.json

Blueprint Structure Explained

Section	Purpose
`metadata`	Name, description, and labels for organization
`spec.ttl`	Time-to-live - auto-destroys environment after this duration
`spec.provider`	Cloud provider and region for infrastructure
`spec.components`	Services to deploy (GitLab, runners, databases, etc.)
`spec.participants`	Participant isolation and resource allocation
`spec.tracking`	Activity monitoring configuration
`spec.hooks`	Custom scripts for lifecycle events

Step 2: Validate the Blueprint

Before deploying, validate your blueprint for errors:

teactl blueprint validate cicd-workshop.yaml

Expected output:

Validating blueprint 'cicd-workshop'...

✓ Schema validation passed
✓ Component dependencies resolved
✓ Resource requirements within quota
✓ Provider 'hetzner' available in region 'eu-central'

Blueprint Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Name:           cicd-workshop
  Components:     2 (gitlab, runner)
  Participants:   10 max
  TTL:            8 hours

  Resource Totals:
    vCPUs:        18 (4 + 2×2 + 10×1)
    Memory:       36 GB (8 + 2×4 + 10×2)
    Storage:      150 GB (50 + 2×20 + 10×10)

  Estimated Cost: $18.50/session

✓ Blueprint 'cicd-workshop' is valid and ready to deploy

Common Validation Errors

Error	Solution
“Unknown component type”	Check `type` field matches available components
“Insufficient quota”	Reduce resources or upgrade your plan
“Invalid region”	Use `teactl provider regions <provider>` to list valid regions
“Missing required field”	Add the required field to your blueprint

Step 3: Create the Environment

Deploy your training environment:

teactl env create -f cicd-workshop.yaml --name march-workshop

Watch the real-time deployment progress:

Creating environment 'march-workshop'...

Phase 1: Infrastructure Setup
  ✓ Created VPC (vpc-march-workshop-abc123)
  ✓ Configured security groups
  ✓ Provisioned control plane

Phase 2: Core Components
  ⠋ Deploying GitLab instance...
  ✓ GitLab server running (4 vCPU, 8GB RAM)
  ✓ GitLab configured (CI/CD enabled, registry ready)
  ⠋ Deploying CI/CD runners...
  ✓ Runner 1 registered and ready
  ✓ Runner 2 registered and ready

Phase 3: Participant Setup
  ⠋ Creating participant workspaces...
  ✓ Workspace 1/10 ready
  ✓ Workspace 2/10 ready
  ...
  ✓ Workspace 10/10 ready
  ✓ Activity tracking enabled

Phase 4: Finalization
  ✓ DNS records configured
  ✓ TLS certificates issued
  ✓ Access credentials generated

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Environment 'march-workshop' is ready!

  Status:         ready
  Created:        2024-03-15 09:00:00 UTC
  Expires:        2024-03-15 17:00:00 UTC (8h from now)
  Setup time:     8m 42s

  Access Points:
  ├─ GitLab:      https://gitlab.march-workshop.env.teabar.dev
  ├─ Dashboard:   https://app.teabar.dev/envs/march-workshop
  └─ API:         https://api.march-workshop.env.teabar.dev

  Admin Credentials:
    Username: root
    Password: Run 'teactl env creds march-workshop' to reveal

  Next Steps:
    1. Get participant links:  teactl env participants march-workshop
    2. Monitor activity:       teactl env watch march-workshop
    3. View in browser:        teactl env open march-workshop

Deployment Tips

Tip

Add --wait=false to run deployment in background, then check status with teactl env status march-workshop --watch.

Step 4: Invite Participants

Option A: Generate Access Links

Generate unique access links for each participant:

teactl env participants march-workshop --links

Output:

Participant Access for 'march-workshop'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Access links (share with participants):

  #1   https://teabar.dev/join/march-workshop/p1-a7b3c9
  #2   https://teabar.dev/join/march-workshop/p2-d4e5f6
  #3   https://teabar.dev/join/march-workshop/p3-g7h8i9
  #4   https://teabar.dev/join/march-workshop/p4-j0k1l2
  #5   https://teabar.dev/join/march-workshop/p5-m3n4o5
  #6   https://teabar.dev/join/march-workshop/p6-p6q7r8
  #7   https://teabar.dev/join/march-workshop/p7-s9t0u1
  #8   https://teabar.dev/join/march-workshop/p8-v2w3x4
  #9   https://teabar.dev/join/march-workshop/p9-y5z6a7
  #10  https://teabar.dev/join/march-workshop/p10-b8c9d0

Each link provides:
  • Unique GitLab account (developer access)
  • Isolated Kubernetes namespace
  • Pre-cloned exercise repositories
  • Personal terminal access

Export as CSV: teactl env participants march-workshop --format csv

Option B: Email Invitations

Send invitations directly to participants:

# From a list of emails
teactl env invite march-workshop 
  --emails [email protected],[email protected],[email protected]

# From a CSV file
teactl env invite march-workshop --file participants.csv

CSV format:

email,name
[email protected],Alice Smith
[email protected],Bob Jones
[email protected],Charlie Brown

Participants receive an email with:

Direct access link
Environment details
Getting started instructions

Option C: Self-Registration Link

Create a single link for self-registration:

teactl env registration-link march-workshop

Registration Link (first 10 to join):
https://teabar.dev/join/march-workshop/register

Share this link. Participants claim spots on first-come basis.
Remaining spots: 10

Step 5: Participant Experience

When participants click their access link, they see:

┌─────────────────────────────────────────────────────────┐
│                                                          │
│            Welcome to march-workshop                     │
│            CI/CD Training Environment                    │
│                                                          │
│  ──────────────────────────────────────────────────────  │
│                                                          │
│  Your Workspace:                                         │
│  • Username:    participant-03                           │
│  • Namespace:   p03-workspace                            │
│                                                          │
│  Access Points:                                          │
│  ├─ GitLab:     [Open GitLab]                           │
│  ├─ Terminal:   [Open Terminal]                          │
│  └─ Exercises:  [View Exercises]                         │
│                                                          │
│  Pre-Cloned Repositories:                                │
│  • hello-ci (GitLab CI basics)                          │
│  • docker-build (Docker pipelines)                       │
│                                                          │
│  Time Remaining: 7h 23m                                  │
│                                                          │
└─────────────────────────────────────────────────────────┘

Each participant has:

Resource	Details
GitLab Account	`participant-XX` with developer access
Kubernetes Namespace	Isolated namespace with edit permissions
Terminal	Web-based terminal with pre-configured tools
Repositories	Exercise repos pre-cloned to workspace

Step 6: Monitor Activity

Real-Time Dashboard

Open the activity dashboard:

teactl env watch march-workshop

┌─ march-workshop ─────────────────────────────────────────────────┐
│ Status: running │ Uptime: 1:23:45 │ TTL: 6:36:15 │ Cost: $2.85   │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Participants (8/10 active)                                       │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                   │
│  ● Alice (p01)     ████████████████████ 100%  ★ All milestones   │
│  ● Bob (p02)       ██████████████░░░░░░  70%  ✓ Pipeline Success │
│  ● Charlie (p03)   ████████████░░░░░░░░  60%  ✓ First Push       │
│  ● Diana (p04)     ██████████░░░░░░░░░░  50%  ✓ First Push       │
│  ● Eve (p05)       ████████░░░░░░░░░░░░  40%  ⠋ Working...       │
│  ● Frank (p06)     ██████░░░░░░░░░░░░░░  30%  ✓ First Push       │
│  ● Grace (p07)     ████░░░░░░░░░░░░░░░░  20%  ⠋ Working...       │
│  ● Henry (p08)     ██░░░░░░░░░░░░░░░░░░  10%  Just joined        │
│  ○ (p09)           ░░░░░░░░░░░░░░░░░░░░   0%  Not joined         │
│  ○ (p10)           ░░░░░░░░░░░░░░░░░░░░   0%  Not joined         │
│                                                                   │
│  Recent Activity (press 'a' for full log)                        │
│  ─────────────────────────────────────────────────────────────── │
│  10:23:45  Alice   Pipeline #5 passed (main)                     │
│  10:23:12  Bob     Pushed to feature/add-tests                   │
│  10:22:58  Diana   Created .gitlab-ci.yml                        │
│  10:22:30  Eve     Cloned docker-build repository                │
│  10:21:45  Charlie Pipeline #2 failed (syntax error)             │
│                                                                   │
│  Milestones                                                       │
│  ─────────────────────────────────────────────────────────────── │
│  First Push:       6/8 participants (75%)                        │
│  Pipeline Success: 2/8 participants (25%)                        │
│                                                                   │
├──────────────────────────────────────────────────────────────────┤
│ [q]uit [a]ctivity [p]articipants [h]elp [r]efresh                │
└──────────────────────────────────────────────────────────────────┘

CLI Queries

Check specific participant activity:

# View participant details
teactl env participant march-workshop p03

# View all activity
teactl env activity march-workshop

# Filter by event type
teactl env activity march-workshop --event pipeline-run

# Export activity log
teactl env activity march-workshop --format json > activity.json

Web Dashboard

Open the web dashboard for a graphical view:

teactl env open march-workshop --dashboard

Or visit: https://app.teabar.dev/envs/march-workshop

Step 7: Manage the Session

Extend the TTL

Need more time? Extend the environment:

# Add 2 more hours
teactl env extend march-workshop --duration 2h

# Extend to specific time
teactl env extend march-workshop --until "2024-03-15 20:00"

Send Announcements

Broadcast messages to all participants:

teactl env announce march-workshop "15 minutes remaining! Please save your work."

Participants see the message in their terminal and web interface.

Pause/Resume

Pause the environment (stops billing for compute):

# Pause (keeps data, stops compute)
teactl env pause march-workshop

# Resume later
teactl env resume march-workshop

Create Checkpoint

Save the current state for later restoration:

teactl env checkpoint march-workshop --name "end-of-day-1"

Restore from checkpoint:

teactl env restore march-workshop --checkpoint "end-of-day-1"

Step 8: End the Session

Review Summary

Get a session summary before destroying:

teactl env summary march-workshop

Session Summary: march-workshop
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Duration:         8h 12m
Participants:     8/10 joined

Activity Overview:
  Total events:   342
  Git pushes:     89
  Pipeline runs:  67 (52 passed, 15 failed)

Milestone Completion:
  First Push:       8/8 (100%)
  Pipeline Success: 6/8 (75%)

Top Performers:
  1. Alice (p01)  - All milestones, 12 commits
  2. Bob (p02)    - 8 commits, 5 pipelines
  3. Diana (p04)  - 6 commits, 3 pipelines

Cost Breakdown:
  GitLab:         $5.20
  Runners (2):    $4.10
  Workspaces:     $5.80
  Storage:        $0.90
  ──────────────────────
  Total:          $16.00

Export Data

Export session data before destroying:

# Export activity log
teactl env export march-workshop --activity -o activity.json

# Export participant data
teactl env export march-workshop --participants -o participants.csv

# Export everything
teactl env export march-workshop --all -o march-workshop-export/

Destroy Environment

When finished, destroy the environment:

teactl env destroy march-workshop

Destroying environment 'march-workshop'...

Are you sure? This will permanently delete:
  • All participant workspaces and data
  • GitLab repositories and CI/CD history
  • Activity tracking logs

Type 'march-workshop' to confirm: march-workshop

  ✓ Notified active participants
  ✓ Exported activity log to ~/.teabar/exports/march-workshop/
  ✓ Terminated participant workspaces (10/10)
  ✓ Terminated GitLab instance
  ✓ Terminated CI/CD runners
  ✓ Deleted networking resources
  ✓ Released IP addresses
  ✓ Cleaned up DNS records

Environment 'march-workshop' destroyed.

Session Summary:
  Duration:  8h 12m
  Cost:      $16.00
  Data:      Exported to ~/.teabar/exports/march-workshop/

Warning

Destruction is permanent! All data is deleted. Use checkpoints or exports to preserve important data before destroying.

Troubleshooting

Environment Stuck Creating

# Check detailed status
teactl env status march-workshop --verbose

# View provisioning logs
teactl env logs march-workshop --follow

# Force cancel and retry
teactl env destroy march-workshop --force
teactl env create -f cicd-workshop.yaml --name march-workshop

Participant Can’t Access

# Check participant status
teactl env participant march-workshop p03

# Regenerate credentials
teactl env participant march-workshop p03 --regenerate

# View participant logs
teactl env logs march-workshop --participant p03

GitLab Slow or Unresponsive

# Check component health
teactl env health march-workshop

# View GitLab logs
teactl env logs march-workshop --component gitlab

# Restart GitLab (if needed)
teactl env restart march-workshop --component gitlab

Pipeline Runners Not Working

# Check runner status
teactl env runners march-workshop

# View runner logs
teactl env logs march-workshop --component runner

# Scale runners
teactl env scale march-workshop --component runner --count 3

Best Practices

Before the Session

Test your blueprint with 1-2 participants first
Pre-run exercises to verify they work
Set appropriate TTL with buffer time
Prepare backup plan in case of issues

During the Session

Monitor activity dashboard to identify struggling participants
Use announcements for time warnings
Create checkpoints at key milestones
Have fallback environments ready

After the Session

Export activity data for analysis
Collect feedback from participants
Review costs and optimize for next time
Update blueprint based on learnings

Next Steps

Blueprint Syntax Reference - All configuration options
Participant Management - Advanced participant features
Activity Tracking - Detailed tracking configuration
Community Blueprints - Ready-to-use templates

Tip

Need help planning your training session? Email [email protected] for personalized guidance.