Lab

Defined inmain.hcl

The lab resource defines the main configuration for your lab, including metadata, settings, layout, and content structure. This is equivalent to what was previously called a “track” in legacy formats.

Use Cases

As a lab author, you use the lab resource to define the overall lab experience:

• Learning Structure: Organize content into logical chapters and pages that guide users through progressive learning experiences
• Time Management: Configure time limits, extensions, and idle behavior to ensure appropriate pacing for learning objectives
• Interactive Learning: Structure labs to include tasks, quizzes, and other interactive elements that validate learning outcomes

The lab resource serves as the foundation that ties together all other lab components into a cohesive learning experience.

HCL Syntax

Basic Syntax

resource "lab" "name" {
  title       = "My Lab"
  description = "A brief description of what this lab teaches"
  layout      = resource.layout.two_column

  settings {
    timelimit {
      duration = "1h"
    }
  }

  content {
    chapter "introduction" {
      title = "Getting Started"

      page "welcome" {
        reference = resource.page.welcome
      }
    }
  }
}

Full Syntax

resource "lab" "name" {
  title       = "My Lab"
  description = "A comprehensive description of the lab"

  settings {
    theme = "modern-dark"

    timelimit {
      duration   = "30m"
      extend     = "5m"
      show_timer = true
    }

    idle {
      enabled      = true
      timeout      = "10m"
      show_warning = true
    }

    controls {
      show_stop = true
    }
  }

  layout = resource.layout.default

  content {
    title = "Lab Instructions"

    chapter "chapter1" {
      title  = "Introduction"
      layout = resource.layout.single_column

      page "page1" {
        title     = "Welcome"
        layout    = resource.layout.two_column
        reference = resource.page.welcome
      }
    }
  }
}

Resource Structure

lab
├─ title, description (metadata)
├─ layout (reference to default layout)
├─ settings
│  ├─ theme
│  ├─ timelimit
│  │  ├─ duration, extend, show_timer
│  ├─ idle
│  │  ├─ enabled, timeout, show_warning
│  └─ controls
│     └─ show_stop
└─ content
   ├─ title
   └─ chapters[]
      ├─ title, layout (optional override)
      └─ pages[]
         ├─ title (optional override), layout (optional override)
         └─ reference (to page resource)

A lab needs a time limit to run

The schema treats settings and its timelimit block as optional, so a lab without them validates. It will not start: sessions are refused when the lab has no session time limit configured. Give every lab a settings block with timelimit.duration. The idle block stays optional; leave it out and the idle timeout is off.

Fields

Field	Type	Required	Description
title	string	✓	Lab title displayed to users
description	string	✓	The description introduces your lab to learners. Explain what it covers, its purpose, and any prerequisites or outcomes.
icon	string	—	Lab icon image, either an asset path within the assets/ directory or an external URL
settings	block	—	Lab behavior settings
layout	referencelayout	✓	Default layout for the lab
content	block	—	Lab content structure with chapters and pages

Settings

lab→Settings

Lab behavior settings

Field	Type	Required	Description
theme	string	—	Themes define the visual style of your lab interface. Choose one that best fits your content and brand. Allowedmodern-dark original Defaultmodern-dark
timelimit	block	—	Time limit configuration
idle	block	—	Idle timeout configuration
controls	block	—	UI control visibility

Time Limit

lab→Settings→Time Limit

Time limit configuration

Field	Type	Required	Description
duration	string	—	Maximum duration the lab can run before automatically shutting down ConstraintsMust be a valid duration (e.g., 30m, 1h, 1h30m)
extend	string	—	Allow learners to extend their lab session when they reach the time limit ConstraintsMust be a valid duration (e.g., 30m, 1h, 1h30m)
show_timer	bool	—	Show or hide the timer for learners during the lab Defaulttrue

Idle Timeout

lab→Settings→Idle Timeout

Idle timeout configuration

Field	Type	Required	Description
enabled	bool	—	Define how long a lab can stay inactive before it stops automatically Defaulttrue
timeout	string	—	Automatically stops the lab after a period of user inactivity, conserving resources when sessions are unattended ConstraintsMust be a valid duration (e.g., 30m, 1h, 1h30m)
show_warning	bool	—	Show a warning to learners before their session is stopped due to inactivity Defaulttrue

Controls

lab→Settings→Controls

UI control visibility

Field	Type	Required	Description
show_stop	bool	—	Control whether the stop button is visible to learners. Turning it off prevents users from stopping the lab manually. Defaulttrue

Content

lab→Content

Lab content structure with chapters and pages

Field	Type	Required	Description
title	string	—	Content section title
chapter	block	—	Content chaptersrepeatable

Chapter

lab→Content→Chapter

Content chapters

Field	Type	Required	Description
slug	label	—	Chapter slug identifier
title	string	✓	Chapter title
layout	referencelayout	—	Chapter-specific layout override
page	block	—	Pages within this chapterrepeatable

Page

lab→Content→Chapter→Page

Pages within this chapter

Field	Type	Required	Description
slug	label	—	Page slug identifier
title	string	—	Page title override
layout	referencelayout	—	Page-specific layout override
reference	referencepage	✓	Reference to the page resource

Tags, maintenance mode, and skipping are not configured in HCL

These settings apply to the lab as a whole rather than to a specific version of your configuration:

• Tags: Managed in Lab settings → General. See Project Settings.
• Maintenance mode: Managed in Lab settings → Danger zone. See Project Settings.
• Skipping: In 2.0, learners can always skip tasks and quizzes. There is no skipping_enabled toggle. When a user skips a task, its solve scripts run automatically. Skipping a quiz does not reveal its answers.

Examples

Minimal Lab

resource "lab" "basic" {
  title       = "Docker Basics"
  description = "Learn Docker fundamentals"
  layout      = resource.layout.two_column

  settings {
    timelimit {
      duration = "1h"
    }
  }

  content {
    chapter "intro" {
      title = "Introduction"

      page "welcome" {
        reference = resource.page.welcome
      }
    }
  }
}

Lab Without Visible Chapters

Pages always live inside a chapter, but you can hide the chapter level from learners by using a single chapter labeled __default. The lab then presents its pages as a flat list - useful for short labs where chapter navigation adds noise:

resource "lab" "simple" {
  title       = "Quick Environment Tour"
  description = "A short lab without chapter navigation"
  layout      = resource.layout.two_column

  settings {
    timelimit {
      duration = "30m"
    }
  }

  content {
    chapter "__default" {
      title = "Default"

      page "environment" {
        reference = resource.page.environment
      }
    }
  }
}

Lab with Custom Settings

resource "lab" "advanced" {
  title       = "Kubernetes Deep Dive"
  description = "Advanced Kubernetes concepts and practices"

  settings {
    theme = "original"

    timelimit {
      duration   = "2h"
      extend     = "30m"
      show_timer = true
    }

    idle {
      timeout = "15m"
    }
  }

  layout = resource.layout.three_column

  content {
    title = "Course Material"

    chapter "setup" {
      title = "Environment Setup"

      page "requirements" {
        reference = resource.page.requirements
      }

      page "installation" {
        reference = resource.page.installation
      }
    }

    chapter "basics" {
      title = "Kubernetes Basics"
      layout = resource.layout.two_column

      page "pods" {
        reference = resource.page.pods
      }

      page "services" {
        reference = resource.page.services
      }
    }
  }
}

Layout Inheritance

Layouts are inherited in the following order (most specific wins):

1. Page-level layout (highest priority)
2. Chapter-level layout
3. Lab-level layout (lowest priority)

resource "lab" "example" {
  layout = resource.layout.default  # Applied to all pages by default

  content {
    chapter "intro" {
      layout = resource.layout.two_column  # Overrides lab default for all pages in this chapter

      page "welcome" {
        reference = resource.page.welcome  # Uses chapter layout
      }

      page "setup" {
        layout    = resource.layout.three_column  # Overrides chapter layout for this page only
        reference = resource.page.setup
      }
    }
  }
}

Best Practices

1. Descriptive Titles: Use clear, descriptive titles for labs and chapters
2. Appropriate Timeframes: Set realistic time limits based on lab complexity
3. Tag Consistently: Use consistent tags across labs for better organization (tags are set in Lab settings → General)
4. Layout Hierarchy: Use layout inheritance to minimize repetition
5. Chapter Organization: Group related pages into logical chapters