Creating your first lab

Before you begin, ensure you have gone through the setup and configuration mentioned at the start of the getting started guide.

Create a New Lab from a starter template

Start by initializing a new lab from one of the starter templates, using the instruqt CLI. In your terminal, run the following command and follow the steps in the CLI.

instruqt lab init

You will be prompted to provide the title of the lab e.g. "My First Lab". This will be used to create a target directory on your machine for your configuration based on the sluggified title e.g. my-first-lab. The directory will be created in the current directory you are running the CLI command from.

The CLI will then prompt you to select one of the starter templates to base your lab on. For the purposes of this guide, we will be starting from the "Empty/Skeleton" template. Depending on which template you choose, the configuration will contain additional configuration to assist in that use-case.

Once the template is chosen, review the details and confirm to create the lab. For example, given the title of "My First Lab", the directory structure will resemble:

my-first-lab
├── assets/README.md
├── files/README.md
├── instructions/README.md
├── notes/README.md
├── scripts/README.md
├── layouts.hcl
├── main.hcl
└── README.md

Creating a new lab from template.

Create a Repository on GitHub

In order to get your lab into the Instruqt platform, we will use the GitHub integration which makes it possible to use your standard developer workflows to manage your content. Log into your GitHub account and create a new, empty repository that will store your lab configuration. It is also possible to use mono-repositories to store your labs, but for the purpose of this guide we will create a separate repository specifically for this lab.

From your GitHub dashboard perform the following actions to create a repository in your own user account:

• Click the New button.

• Set the Repository Name. This can match your lab directory, e.g., my-first-lab, but is not required.

• Optionally, add a description.

• Choose the visibility (public or private).

• Do not initialize with a README, .gitignore, or license. This is to keep the initial commit simpler, so you do not have to merge these changes to the README.md.

• Click Create Repository.

You should now have an empty repository, and should see instructions how to interact with the repository. Copy the url in the input field of the "Quick setup — if you’ve done this kind of thing before" section of the instructions. For example if you named the repository my-first-lab, it should look something like:

[e-mail]:my-username/my-first-lab.git

Push the Lab to GitHub

Open up your terminal and navigate to the lab directory you created in Step 1. If you did not do anything in the terminal after running instruqt lab init, you should just run:

cd my-first-lab

Otherwise navigate to the full path of the lab directory instead:

cd /path/to/my-first-lab

Now that you are in the lab directory, you need to initialize the git repository.

git init

We are going to use main as the default branch name from now on, but feel free to just use git init and use master instead.

To set main as the default branch:

git branch -m main

You can then link your local directory to the repository you created on GitHub in Step 2. To do this, use the url you copied at the end of Step 2 and replace the url in the example below with your url:

git remote add origin [e-mail]:my-username/my-first-lab.git

Now that you have linked the local directory to the remote repository, you can add the files and commit them. This will tell git which files you want to include in the commit, and the commit will store the changes to those files in version control and the git history.

Because we want to include all files in the current directory, we can use . as the files we want to include, which means "everything in the current directory".

git add .

Then commit the changes and write a short message that describes what the changes are that are included in the commit. Because this is the first change to the repository, a common commit message to use is "Initial commit".

git commit -m "Initial commit"

Now that the changes are stored in git and recorded in the history, you can push them to the remote repository by running the git push command. Because this is the first time you are pushing to the remote repository, you will need to set the upstream branch.

git push -u origin main

If you get an error stating refspec main does not match any, your default branch is not called main. Use the default branch name instead.

Import the Lab into Instruqt

Now that all configuration is done, we can import the lab from GitHub into the Instruqt platform. First log into your Instruqt account and navigate to the "Labs" section. Click the "Import Lab" button and select the repository you have created in Step 2, then click "Next". If you do not see your lab, make sure that the Instruqt GitHub application has access to the repository.

Fill out the form by entering a name for your lab, e.g. my-first-lab. This will be used as the slug of the lab.

If you are using branches and the lab lives on a different branch than main, or if you want a specific branch/tag of your lab, you can specify the "ref". For the purpose of the guide, we can leave this blank and use the default ref that comes from the GitHub repository.

Next, fill in the path where the lab is located within the repository. If you are using a mono-repository, this is where you can select the directory the lab is in. For the purpose of this guide we can just leave it empty, which will default to the root path / of the directory.

The repository url is shown as the bottom of the form for reference.

You can then click "Import" to start importing your lab. All branches and tags of the repository will be imported and parsed, so you can launch any of them if needed.

Test the Lab in Instruqt

Now that the lab is imported, we can launch it to test it out. From the labs list, locate your lab e.g. my-first-lab and make sure that the status behind the lab has a checkmark and a text similar to #8ec1470 Success. The first part of the success message is the hash of the latest commit that was found on GitHub.

Click the "Start" button on your lab, this will create your lab environment and redirect you to the Lab UI for your lab. Once the lab environment is ready, click the "Enter Lab" button to enter your lab.

Explore the bare Instruqt lab as it will look for your end users. It looks a bit barren at the moment. In the next sections, you will explore adding some basic functionality to your labs.

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.