Skip to content

You are viewing documentation for Instruqt 2.0 Labs. For Tracks documentation, please visit docs.instruqt.com.

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.

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.

resource "lab" "main" {
title = "Kubernetes Platform"
description = "Run the web, API, worker and database of an app on Kubernetes."
layout = resource.layout.app_layout
settings {
timelimit {
duration = "1h"
}
}
content {
chapter "introduction" {
title = "Getting Started"
page "welcome" {
reference = resource.page.welcome
}
}
}
}
resource "lab" "main" {
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
}
}
}
}
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)

Fields

FieldTypeRequiredDescription
titlestring✓Lab title displayed to users
descriptionstring✓The description introduces your lab to users. Explain what it covers, its purpose, and any prerequisites or outcomes.
iconstring—Lab icon image, either an asset path within the assets/ directory or an external URL
settingsblock—Lab behavior settings
layoutreferencelayout✓Default layout for the lab
contentblock—Lab content structure with chapters and pages

Settings

lab→Settings

Lab behavior settings

FieldTypeRequiredDescription
themestring—Themes define the visual style of your lab interface. Choose one that best fits your content and brand.
Allowedmodern-dark modern-light original original-light
Defaultmodern-dark
timelimitblock—Time limit configuration
idleblock—Idle timeout configuration
controlsblock—UI control visibility

Time Limit

lab→Settings→Time Limit

Time limit configuration

FieldTypeRequiredDescription
durationstring—Maximum duration the lab can run before automatically shutting down
Default15m
ConstraintsMust be a valid duration (e.g., 30m, 1h, 1h30m)
extendstring—Allow users to extend their lab session when they reach the time limit
ConstraintsMust be a valid duration (e.g., 30m, 1h, 1h30m)
show_timerbool—Show or hide the timer for users during the lab
Defaulttrue

Idle Timeout

lab→Settings→Idle Timeout

Idle timeout configuration

FieldTypeRequiredDescription
enabledbool—Define how long a lab can stay inactive before it stops automatically
Defaulttrue
timeoutstring—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_warningbool—Show a warning to users before their session is stopped due to inactivity
Defaulttrue

Controls

lab→Settings→Controls

UI control visibility

FieldTypeRequiredDescription
show_stopbool—Control whether the stop button is visible to users. Turning it off prevents users from stopping the lab manually.
Defaulttrue

Content

lab→Content

Lab content structure with chapters and pages

FieldTypeRequiredDescription
titlestring—Content section title
chapterblock—Content chaptersrepeatable

Chapter

lab→Content→Chapter

Content chapters

FieldTypeRequiredDescription
sluglabel—Chapter slug identifier
titlestring✓Chapter title
layoutreferencelayout—Chapter-specific layout override
pageblock—Pages within this chapterrepeatable
Page

lab→Content→Chapter→Page

Pages within this chapter

FieldTypeRequiredDescription
sluglabel—Page slug identifier
titlestring—Page title override
layoutreferencelayout—Page-specific layout override
referencereferencepage✓Reference to the page resource
resource "lab" "main" {
title = "Nomad Platform"
description = "Run the web, API and worker jobs of an app on Nomad clusters."
layout = resource.layout.default
settings {
timelimit {
duration = "1h"
}
}
content {
chapter "intro" {
title = "Introduction"
page "welcome" {
reference = resource.page.welcome
}
}
}
}

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, which is useful for short labs where chapter navigation adds noise:

resource "lab" "main" {
title = "Utilities"
description = "Generate the values, certificates and images an app's lab needs."
layout = resource.layout.default
settings {
timelimit {
duration = "30m"
}
}
content {
chapter "__default" {
title = "Default"
page "environment" {
reference = resource.page.environment
}
}
}
}
resource "lab" "main" {
title = "Cloud Platform"
description = "Give learners cloud accounts to deploy the app to."
settings {
theme = "original"
timelimit {
duration = "2h"
extend = "30m"
show_timer = true
}
idle {
timeout = "15m"
}
}
layout = resource.layout.main
content {
title = "Course Material"
chapter "setup" {
title = "Environment Setup"
page "requirements" {
reference = resource.page.requirements
}
page "installation" {
reference = resource.page.installation
}
}
chapter "basics" {
title = "Cloud Basics"
layout = resource.layout.shell_only
page "accounts" {
reference = resource.page.accounts
}
page "credentials" {
reference = resource.page.credentials
}
}
}
}

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" "main" {
title = "App Platform"
description = "Run the web, API, database and cache of an app on containers and VMs."
layout = resource.layout.default # Applied to all pages by default
content {
chapter "intro" {
title = "Introduction"
layout = resource.layout.with_editor # Overrides lab default for all pages in this chapter
page "welcome" {
reference = resource.page.welcome # Uses chapter layout
}
page "setup" {
layout = resource.layout.multi_terminal # Overrides chapter layout for this page only
reference = resource.page.setup
}
}
}
}
  1. Descriptive Titles: Use clear, descriptive titles for labs and chapters
  2. Appropriate Timeframes: Set realistic time limits based on lab complexity; the 15-minute default only suits short labs
  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