Step 3 - Content & Tasks

With your infrastructure ready, it’s time to make your lab interactive. In this step, you’ll create engaging content that guides users through hands-on activities. You’ll write validation scripts that check their progress, provide helpful feedback when they get stuck, and celebrate their success when they complete tasks correctly.

Create Your First Interactive Task

Tasks make your lab interactive. They define specific activities that users must complete, and they are automatically checked to verify their success.

Add this task definition to tasks.hcl:

1
resource "task" "edit_homepage" {
2
  description = "Customize the nginx homepage with your own message"
3

4
  config {
5
    target = resource.container.webserver
6
  }
7

8
  condition "file_modified" {
9
    description = "Customize the nginx homepage with your own message"
10

11
    check {
12
      script = "scripts/check_homepage.sh"
13
      failure_message = "Please edit /usr/share/nginx/html/index.html with your custom message"
14
    }
15
  }
16
}

Three blocks do the work here:

config decides where the task’s scripts run. target = resource.container.webserver runs them inside your web server container, so they see the same files and environment as the user.
condition is one part of the task that has to pass. Its label, "file_modified", is an id you pick yourself, not a built-in check type. A task can hold several conditions, which lets you give users feedback per step. The condition’s description is what they read on the task.
check is the script that decides whether the condition passed. It runs whenever the task is validated. Exit 0 means passed; any other exit code means not yet, and the user is shown the failure_message.

Build the Validation Script

Now you’ll create the actual script that checks whether users completed the task correctly. This script uses simple bash commands to look for specific content in the nginx homepage file. If it finds the expected text, the task passes; if not, it fails with a helpful message.

Remember, this script runs inside the container, so it can directly check files that users modified.

Create the validation script directory and file:

mkdir -p scripts

In VS Code, create a new file scripts/check_homepage.sh:

1
#!/bin/bash
2

3
EXPECTED_MESSAGE="Hello from my web server!"
4
NGINX_HTML="/usr/share/nginx/html/index.html"
5

6
if grep -q "$EXPECTED_MESSAGE" "$NGINX_HTML"; then
7
  exit 0
8
else
9
  exit 1
10
fi

Make the script executable:

chmod +x scripts/check_homepage.sh

Create User Instructions

Now you need to create the actual content that users will see and follow. This includes step-by-step instructions that guide them through customizing the nginx homepage.

Create the instruction content directory:

mkdir -p instructions

In VS Code, create a new file instructions/customize_homepage.md with this content:

1
# Customize Your Web Server
2

3
Web servers like nginx serve static files to visitors who access your website. When someone types your website's URL into their browser, nginx looks for an `index.html` file in its web directory and sends that content back to display in the browser.
4

5
## Understanding Web Server File Structure
6

7
Nginx stores its web files in `/usr/share/nginx/html/` by default. The main file, `index.html`, contains the HTML code that creates your homepage. Any changes you make to this file will immediately be visible to visitors since nginx serves static files directly without requiring a restart.
8

9
## Working with HTML Files
10

11
HTML (HyperText Markup Language) uses tags to structure content. You can add text, headings, paragraphs, and other elements by using HTML tags like:
12

13
- `<h1>` for main headings
14
- `<p>` for paragraphs
15
- `<strong>` for bold text
16

17
## Editing Files on a Server
18

19
Minimal container images like nginx ship without a text editor, so you change files with shell commands instead. In the Terminal tab, replace the homepage with your own message:
20

21
```bash
22
echo '<h1>Hello from my web server!</h1>' > /usr/share/nginx/html/index.html
23
```
24

25
Verify your change with `cat`:
26

27
```bash
28
cat /usr/share/nginx/html/index.html
29
```
30

31
To see your changes, refresh your browser or the Service tab.
32

33
<instruqt-task id="edit_homepage"></instruqt-task>
34

35
## Troubleshooting
36

37
**Can't find the file?**
38

39
- Make sure you're in the right directory: `/usr/share/nginx/html`
40
- List files with: `ls -la`
41

42
**Changes not showing?**
43

44
- Force refresh the Service tab (Ctrl+F5 or Cmd+Shift+R)
45
- Wait a few seconds and refresh again
46

47
## Finish the Lab
48

49
<instruqt-completion text="You customized a live web server and validated your change with an automated check."></instruqt-completion>

Two embedded components make this page interactive:

<instruqt-task> shows the task you defined earlier inside the instructions.
<instruqt-completion> adds the Completion panel. Labs have no built-in finish button, so without this panel users can’t end the session. The panel shows the user’s progress. When every activity is done, it shows a Finish & Exit button that stops the lab and its sandbox. See the Completion component docs for its options.

Create the Layout Configuration

Layouts define how the lab’s user interface is organized on screen. Multi-column layouts work well for instructional labs - users can read instructions alongside practice areas and see results in real-time. This keeps everything visible at once, reducing the need to switch between tabs.

The layout connects to your infrastructure by referencing the terminal and service resources you created earlier.

Define the user interface with layouts.hcl:

1
resource "layout" "two_column" {
2
  column {
3
    width = "50"
4

5
    instructions {}
6
  }
7

8
  column {
9
    width = "50"
10

11
    tab "terminal" {
12
      title  = "Terminal"
13
      target = resource.terminal.shell
14
    }
15

16
    tab "service" {
17
      title  = "Service"
18
      target = resource.service.webserver
19
    }
20
  }
21
}

This layout creates two equal-width columns (50% each):

Left column: Shows the instruction content you’ll create next, using the instructions {} block
Right column: Contains two tabs that users can switch between:
- Terminal tab for running commands (references your shell resource)
- Service tab for viewing the web server (references your webserver service)

Each tab block has a label, such as "terminal", that must be unique within the layout. Error messages call this label the tab’s slug.

The target attribute points the tab at a resource you defined earlier, such as resource.terminal.shell. Tab targets take the resource reference directly. Add .meta.id only where a field asks for an ID, such as network { id = resource.network.main.meta.id } in your infrastructure file.

Create Page Structure

Pages are the building blocks of your lab’s content. Each page is a step in your lab where users read instructions and complete activities. This page definition ties together the markdown content and the interactive task.

Create a pages.hcl file to organize your content:

1
resource "page" "customize_homepage" {
2
  title = "Customize Your Web Server"
3
  file = "instructions/customize_homepage.md"
4

5
  activities = {
6
    edit_homepage = resource.task.edit_homepage
7
  }
8
}

This page configuration:

Points to your markdown file with the educational content using the file field
Connects to your task through the activities map

The activities map is crucial - it tells Instruqt which tasks are available on this page. When users see the <instruqt-task id="edit_homepage"> component in your markdown, Instruqt knows to connect it to the actual task definition. The key (edit_homepage) must match the ID used in the markdown file.

Update Your Lab Configuration

The skeleton template created a basic main.hcl file, but it doesn’t know about all the new resources you’ve created. You need to update it to reference your custom layout and page so users can access your content.

Update the skeleton’s main.hcl to reference your new content:

1
resource "lab" "main" {
2
  title = "My Web Server Lab"
3
  description = "Learn web server basics by customizing an nginx homepage"
4
  layout = resource.layout.two_column
5

6
  settings {
7
    timelimit {
8
      duration = "1h"
9
    }
10
  }
11

12
  content {
13
    chapter "getting_started" {
14
      title = "Getting Started with Web Servers"
15

16
      page "customize_homepage" {
17
        reference = resource.page.customize_homepage
18
      }
19
    }
20
  }
21
}

This updated configuration:

Updates the layout reference to use your custom two-column layout (resource.layout.two_column)
Sets a time limit - timelimit.duration caps how long a lab session can run (here one hour); the lab won’t run without it. See the timelimit settings in the lab reference for the related options, like extensions and showing a countdown timer.
Adds a content block with the required chapter/page hierarchy
Creates a chapter called “Getting Started with Web Servers”
References your page (customize_homepage) within the chapter

Now that you’ve connected all the components, let’s visualize how everything works together:

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#1f2440', 'primaryTextColor':'#e2e8f0', 'primaryBorderColor':'#2a2f45', 'lineColor':'#ffffff', 'secondaryColor':'#141829', 'tertiaryColor':'#181c32', 'background':'#181c32', 'mainBkg':'#181c32', 'secondBkg':'#181c32', 'tertiaryTextColor':'#e2e8f0', 'edgeLabelBackground':'#181c32', 'clusterBkg':'#181c32'}}}%%
graph TD
  A["Task 'edit_homepage'
  Validates homepage
  changes"] --> B["Page 'customize_homepage'
  Educational content
  + task reference"]
  B --> C["Layout 'two_column'
  Instructions and
  Terminal + Service"]
  B --> D["Lab 'main'
  Chapter structure
  + metadata"]

  E["Instructions
  'customize_homepage.md'"] --> B
  F["Validation Script
  'check_homepage.sh'"] --> A

  style A fill:#667eea,stroke:#2a2f45,color:#ffffff
  style B fill:#667eea,stroke:#2a2f45,color:#ffffff
  style C fill:#667eea,stroke:#2a2f45,color:#ffffff
  style D fill:#667eea,stroke:#2a2f45,color:#ffffff
  style E fill:#4facfe,stroke:#2a2f45,color:#ffffff
  style F fill:#4facfe,stroke:#2a2f45,color:#ffffff

This shows how your content and task components connect: the task validates user actions, the page combines content with the task, and everything is organized through the lab’s chapter structure.

Validate Your Complete Lab

Now that you’ve created all the components and connected them together, it’s important to validate that your complete lab configuration is correct. This checks for syntax errors, missing references, and ensures all your resource connections are properly defined.

Validate that all components work together:

instruqt lab validate

Save Your Complete Lab

Your lab is now fully functional with interactive tasks and validation. Save this milestone to Git so you have a complete working version to build upon or return to if needed.

Stage all your new lab files:

git add .

Create a commit documenting your complete interactive lab:

git commit -m "Add interactive homepage customization activity"

[main def9012] Add interactive homepage customization activity
 6 files changed, 120 insertions(+), 7 deletions(-)
 create mode 100644 instructions/customize_homepage.md
 create mode 100644 pages.hcl
 create mode 100755 scripts/check_homepage.sh
 create mode 100644 tasks.hcl

Push your complete lab to GitHub:

git push

What You’ve Built

You’ve created a complete, interactive Instruqt lab with all the essential components:

Interactive task that validates user progress automatically using custom validation scripts
Educational content with step-by-step instructions that teach web server concepts
Complete lab structure connecting tasks, pages, layouts, and infrastructure through proper resource chaining
Professional organization with clear separation between configuration files, content files, and validation logic

Your lab now provides a complete learning experience where users can read instructions, complete hands-on activities, and receive immediate feedback on their progress. This represents a fully functional Instruqt lab ready for users.

Final Code

Here’s all the code from this step in one place for easy reference:

1
resource "task" "edit_homepage" {
2
  description = "Customize the nginx homepage with your own message"
3

4
  config {
5
    target = resource.container.webserver
6
  }
7

8
  condition "file_modified" {
9
    description = "Customize the nginx homepage with your own message"
10

11
    check {
12
      script = "scripts/check_homepage.sh"
13
      failure_message = "Please edit /usr/share/nginx/html/index.html with your custom message"
14
    }
15
  }
16
}

1
#!/bin/bash
2

3
EXPECTED_MESSAGE="Hello from my web server!"
7 collapsed lines
4
NGINX_HTML="/usr/share/nginx/html/index.html"
5

6
if grep -q "$EXPECTED_MESSAGE" "$NGINX_HTML"; then
7
  exit 0
8
else
9
  exit 1
10
fi

1
# Customize Your Web Server
2

3
Web servers like nginx serve static files to visitors who access your website. When someone types your website's URL into their browser, nginx looks for an `index.html` file in its web directory and sends that content back to display in the browser.
42 collapsed lines
4

5
## Understanding Web Server File Structure
6

7
Nginx stores its web files in `/usr/share/nginx/html/` by default. The main file, `index.html`, contains the HTML code that creates your homepage. Any changes you make to this file will immediately be visible to visitors since nginx serves static files directly without requiring a restart.
8

9
## Working with HTML Files
10

11
HTML (HyperText Markup Language) uses tags to structure content. You can add text, headings, paragraphs, and other elements by using HTML tags like:
12

13
- `<h1>` for main headings
14
- `<p>` for paragraphs
15
- `<strong>` for bold text
16

17
## Editing Files on a Server
18

19
Minimal container images like nginx ship without a text editor, so you change files with shell commands instead. In the Terminal tab, replace the homepage with your own message:
20

21
```bash
22
echo '<h1>Hello from my web server!</h1>' > /usr/share/nginx/html/index.html
23
```
24

25
Verify your change with `cat`:
26

27
```bash
28
cat /usr/share/nginx/html/index.html
29
```
30

31
To see your changes, refresh your browser or the Service tab.
32

33
<instruqt-task id="edit_homepage"></instruqt-task>
34

35
## Troubleshooting
36

37
**Can't find the file?**
38

39
- Make sure you're in the right directory: `/usr/share/nginx/html`
40
- List files with: `ls -la`
41

42
**Changes not showing?**
43

44
- Force refresh the Service tab (Ctrl+F5 or Cmd+Shift+R)
45
- Wait a few seconds and refresh again
46

47
## Finish the Lab
48

49
<instruqt-completion text="You customized a live web server and validated your change with an automated check."></instruqt-completion>

1
resource "layout" "two_column" {
2
  column {
3
    width = "50"
4

5
    instructions {}
6
  }
7

8
  column {
9
    width = "50"
10

11
    tab "terminal" {
12
      title  = "Terminal"
13
      target = resource.terminal.shell
14
    }
15

16
    tab "service" {
17
      title  = "Service"
18
      target = resource.service.webserver
19
    }
20
  }
21
}

1
resource "page" "customize_homepage" {
2
  title = "Customize Your Web Server"
3
  file = "instructions/customize_homepage.md"
4

5
  activities = {
6
    edit_homepage = resource.task.edit_homepage
7
  }
8
}

1
resource "lab" "main" {
2
  title = "My Web Server Lab"
3
  description = "Learn web server basics by customizing an nginx homepage"
4
  layout = resource.layout.two_column
5

6
  settings {
7
    timelimit {
8
      duration = "1h"
9
    }
10
  }
11

12
  content {
13
    chapter "getting_started" {
14
      title = "Getting Started with Web Servers"
15

16
      page "customize_homepage" {
17
        reference = resource.page.customize_homepage
18
      }
19
    }
20
  }
21
}

What’s Next

In the final step, you’ll test your complete lab experience and learn how to deploy it to the Instruqt platform for users to access.