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, lets open the lab directory in your favourite code editor to can take a look around the configuration.

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.

You should see several directories containing a README.md file, explaining what the directories are used for, and two .hcl files that contain a minimal functional configuration for a lab.

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_column" {
    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_column". 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 "instructions". You can later use this name to assign tabs to that panel.

resource "layout" "single_panel" {
  column "instructions" {}
}

Single column layout.

Making changes

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

Change the title of the lab resource located in main.hcl 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 repository in the previous section, we can simply push the changes.

git push

You'll be asked to enter a passphrase. This is the passphrase you created when generating the SSH key. Once you enter the passphrase and hit enter, 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. You can also hover over the status to see the commit timestamp.

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

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.