Configuration files

Learn about configuration files for editing locally.

Overview

Instruqt tracks are Infrastructure-as-Code artifacts and are made up of configuration files that contain all the properties and settings for tracks in YAML and Markdown format. You manage these files either from Web UI or Instruqt CLI. For example, the configuration file track.yml sets track characteristics and can look something like this:

YAML

slug: mytrack
id: baekpuxv2m5g
type: track
title: MyTrack
teaser: Get started quickly with just one container-based sandbox host.
description: Get started quickly with a container-based sandbox host. Choose a container
  when you need a fast, lightweight Linux system.
icon: https://cdn.instruqt.com/assets/templates/ubuntu.png
tags: []
owner: myteam
developers:
- [e-mail]
maintenance: true
show_timer: true
skipping_enabled: true

You probably recognize tracks details like title and teaser as you set them from Web UI. But you can also set these properties by manipulating the track.yml file from your code editor and push your changes with Instruqt CLI to the Instruqt platform.

YAML files use spaces for indentation. Use 2 or 4 spaces for indentation, but no tabs.

To learn how to use these files, read the Edit locally docs.

If you created a track with Instruqt CLI or pulled a track to your machine, you will find the configuration files inside the track directory and subdirectories:

# Example directory layout with track configuration files
.
├── 01-first-challenge          # First challenge
|   ├── assignment.md           # Challenge assignment and configuration
│   ├── check-host01            # Challenge lifecycle scripts
│   └── solve-host01
├── 02-second-challenge         # Second challenge
|   ├── assignment.md
│   ├── setup-host01
│   ├── check-host01
│   ├── solve-host01
│   └── cleanup-host01
├── track_scripts               # Track lifecycle scripts
│   ├── setup-host01
│   └── cleanup-host01
├── config.yml                  # Sandbox configuration
└── track.yml                   # Track configuration

Track level files

Generally speaking, there are four file types at a track level:

config.yaml

The config.yml file contains the sandbox definition of a track.

version: "3"
# container definitions
containers:
- name: <hostname>
  image: <container_image>
  shell: <shell_type>
  memory: <memory_mb>
  
# website host definitions
virtualbrowsers:
- name: <hostname>
  url: <website_urls>

# virtual machine definitions
virtualmachines:
- name: <hostname>
  image: <gcp_project>/<image_name>
  shell: <shell_type>
  machine_type: <machine_size>

# cloud account definitions
gcp_projects:
- name: <project_name>
  services:
  - <service_name>.googleapis.com
  roles: 
  - roles/<role_name>
aws_accounts:
- name: <account_name>
  managed_policies:
  - arn:aws:iam::aws:policy/<policy_name>
azure_subscriptions:
- name: <subcription_name>
  roles:
  - <role_name>
  
# sandbox secrets
secrets:
- name: <secret>

track.yml

The track.yml file contains the track metadata and settings.

slug: <track_slug>
id: <track_id>
title: <track_title>
teaser: <track_teaser>
description: <track_description>
icon: <path_to_icon>
tags: [<tag>,<tag>]
owner: <instruqt_team_name>
developers:
- <developer_email>
idle_timeout: <value_in_seconds>
timelimit: <value_in_seconds>
extend_ttl: <value_in_seconds>
lab_config:
  sidebar_enabled: <boolean>
  feedback_recap_enabled: <boolean>
  feedback_tab_enabled: <boolean>
  loadingMessages: <boolean>
  theme:
    name: <modern-dark_or_original>
  default_layout: <AssignmentRight_or_AssignmentLeft_or_AssignmentBottom>
  default_layout_sidebar_size: <value_between_25_100>
  override_challenge_layout: <boolean>

setup-host

The setup-<hostname> file is the script that runs after a track stops.

Example script

#!/bin/bash
set -euxo pipefail

# Wait for the Instruqt host bootstrap to finish
until [ -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
do
    sleep 1
done

...more commands...

Instruqt scripts can be written in any language, including PowerShell and Python.

cleanup-host

The cleanup-<hostname> file is the script that runs once a host is provisioned.

Example script

#!/bin/bash
set -euxo pipefail

curl -X POST https://my-api.com/delete/resource/X

Instruqt scripts can be written in any language, including PowerShell and Python.

File name	Description
config.yml	Contains the sandbox definition in YAML.
track.yml	Contains the track definition in YAML.
setup-host	Contains a script for setting up the track.
cleanup-host	Contains a script for cleaning up the track.

For more information on Track scripts, read these docs.

Challenge level files

File name	Description
assignment.md	Contains challenge definition in YAML, learner assignment in markdown.
setup-host	Script for setting up the challenge.
check-host	Script for checking if the learner solved the challenge.
solve-host	Script for automatically solving a challenge when a learner skips.
cleanup-host	Script for cleaning up the challenge.

For more information on challenge scripts, read these docs.