Exploring the lab configuration

We will use the skeleton lab we created in the previous section and start adding configuration to it until we have a complete lab.

To start off, we will customize the configuration of the lab resource. Open the lab directory in your favourite code editor. If you still have the terminal open in the lab directory from the last steps, and you are using Visual Studio Code, run:

code .

This will open up Visual Studio Code and all the files in the lab directory. Lets start by taking a look at the main.hcl file, which contains the definition of the lab resource.

resource "lab" "main" {
  title = "Skeleton Lab"
  description = <<-EOF
  This is the Skeleton Lab.
  You can use this as a minimal starting point for developing labs.
  EOF

  layout "single_panel" {
    reference = resource.layout.single_panel
  }
}

Lab

The lab resource is the main entrypoint of your lab configuration, that contains all the configuration for your lab. You can find all the possible settings for a lab in the "Lab reference" section of the documentation.

Besides a title for the lab, it also includes a multi-line description. There are different ways to write text values for fields. If it is a single line, you can simply use double quotes description = "this is my title" to define the value. But if your description is longer you can either use HEREDOC syntax as you can see in the generated skeleton lab and the example above, or use the file() function to use the contents of a local file instead e.g. description = file("README.md").

Below the description field, you can see a layout block that is named single_panel. The layout block defines which layouts are available to the use inside the lab content. This block can be repeated multiple times, with unique names, and they have a reference to a layout resource.

You can reference other resources and fields within those resources by providing the full path to them. In the generated example lab, layout block on the lab is referencing a resource of type layout and a name of single_panel, which results in a reference of resource.layout.single_panel. If for instance you wanted to reference the title field of the lab, you could use resource.lab.main.title to get the value of "Skeleton Lab".

Layouts

The layout resource lets you define your own custom layouts of the Instruqt Lab UI. A layout consists of "panels", defined as nested columns and rows. For each panel, you can define the size of the panel in percentages e.g. "50%".

You can find all the possible settings for a layout in the "Lab reference" section of the documentation.

In the layouts.hcl file there is a generated single panel layout. This layout defines a single column named "main". You can later use this name to assign tabs to that panel.

resource "layout" "single_panel" {
  column "main" {}
}

Making changes

Now lets see what the workflow is to make changes to an existing lab.

Change the title of the lab resource to reflect the title of your lab e.g. "My First Lab", and update the description field to "This is my first lab".

To validate that the lab definition is still correct, you can run the validate command from the lab directory:

instruqt lab validate

If there are any validation errors, the CLI will tell you where and what is incorrect. Please correct any errors, until the lab validates successfully.

Now we can use standard developer workflows using git to manage the lab. To see what changes have been made to the lab, we can check the status:

git status

If there are no unintended changes, we can add the files we want to include in the commit:

git add main.hcl

And then commit the changes with a descriptive message, which helps others that are collaborating on the content to understand what has changed since the last time they worked on the lab.

git commit -m "Update title and description of the lab"

Finally the changes can be pushed to GitHub. Because we have already defined the upstream of the respository in the previous section, we can simply push the changes.

git push

This will trigger the changes to be pulled into the Instruqt platform from GitHub. Head on over to the "Labs" section of the Instruqt platform and find your lab. The status message on the lab should still contain a checkmark and the hash of your new commit on GitHub.

When you start the lab, you should now see your new title and description on the loading screen.