Link Search Menu Expand Document

The index File

A lab’s index file provides configuration about the lab to the underlying Katacoda platform and includes information about the lab’s steps, environment, assets, any foreground/background scripts, and more.

The index file is placed in the root of a lab’s repository. It can be a JSON file or a YAML file, but only one index file should be added to each lab. The JSON file is named index.json. JSON is the original format used by labs and examples in this documentation are primarily given in json format. The YAML file is named index.yaml. It supports the same elements as the JSON file, but in a more concise YAML format.

Root Elements

The following are the root JSON elements allowed in the index.json file:

Element Description
title Title for the lab.
description Description for the lab.
difficulty Difficulty for the lab shown on the intro screen. Optional. Default: "Beginner".
time Time for the lab shown on the intro screen. Optional.
icon Icon to use when displaying the lab panel on Katacoda.com. Deprecated.
details Steps, intro and finish text to display.
files What files to automatically open when using editor-terminal layout.
environment Configure the UI for the lab.
backend Define the environment for the lab.
private Set to true if you want to make the lab only accessible via the Embed API or to other members of your organization within Katacoda. Deprecated in favor of the katacoda.yaml file included in the root of the project repository.

“details” Elements

The following elements go under the "details" element:

Element Description
steps An array of steps for lab.
intro Details for the intro screen.
finish Details for the finish screen.
assets List of files to upload.

Elements for “intro”, “finish”, and “steps”

The following elements go under the "intro", "finish", and "steps" elements:

Element Description
title Title text for the step.
text File of the Markdown file to display.
answer Display an additional Solution screen on the step.
verify Run a script to verify if the user can proceed. Prints “done” to allow the user to proceed.
solution Run a script to apply a solution that will satisfy the verify script to allow authors and the Editorial team to review and test a lab. Prints “done” on success.
background Run script in the background of the terminal session.
foreground Run script in the foreground of the terminal, as if the user had typed it.

“Assets” Elements

The following elements would go under a "host01" or "client" element depending on the target location:

Element Description
file File to upload. Should be within the assets folder in the lab directory. Wildcard (*) support for uploading multiple files or *.sh for only certain extensions, in this case files with sh extension. For uploading all subdirectories, you can use **/*.*.
target Directory to upload the file too within the environment
chmod Set the "+x" flag if it’s a script to be executed. Optional.

client is the container defined in the index.json or index.yaml file, while host01 is where Docker itself is running. For more, see Managing Assets.

“environment” Elements

Element Description
uilayout UI Layout to use. View the list of supported layouts here.
uieditorpath Default path for editor files. Usually within /root directory.
showide Show VS Code IDE in tab. NOTE: This should not be used with the vscode-terminal-split layout.
defaultTab Starting from 0, change the default tab that is selected in the ui.
showdashboard Display additional dashboard links. Required to use dashboards list. If no list provided, the default port from Backend is used.
dashboards See https://www.katacoda.com/scenario-examples/scenarios/dashboard-tabs
terminals See https://www.katacoda.com/scenario-examples/scenarios/dashboard-tabs
exclusionPatterns Hide certain files/folders from the text editor’s tree view. Example is ["*test", "./test/*", "./logs"]. Not supported in VS Code.
hideHiddenFiles Hide hidden files in the text editor’s tree view. Not supported in VS Code. Default false.
uisettings Set the syntax highlighting for the text editor. Not supported in VS Code.
hideintro Should the intro screen be shown at the start? Default false.
hidefinish Should the finish screen be accessible? Default false.
hidesidebar Should the lab’s step-by-step text be hidden? Default false.

“backend” Elements

Element Description
imageid Specify the environment required for the lab. View the list of supported environments here.
port Default port to use for rendering links. Optional

Complete Example for index.json

{
  "title": "Lab Title",
  "description": "Lab Description",
  "difficulty": "beginner",
  "time": "5-10 minutes",
  "details": {
    "steps": [
      {
        "title": "First Step Title",
        "text": "step1.md",
        "answer": "step1-answer.md",
        "verify": "step1-verify.sh",
        "solution": "step1-solution.sh",
        "background": "run-command-in-background.sh",
        "foreground": "run-command-in-terminal.sh"
      },
      {
        "title": "Second Step Title",
        "text": "step2.md"
      }
    ],
    "intro": {
      "text": "intro.md",
      "background": "courseBase.sh",
      "foreground": "changecd.sh"
    },
    "finish": {
      "text": "finish.md"
    },
    "assets": {
      "client": [
        {
          "file": "docker-compose.yml",
          "target": "~/"
        }
      ],
      "host01": [
        {
          "file": "config.yml",
          "target": "~/"
        }
      ]
    }
  },
  "files": [
    "app.js"
  ],
  "environment": {
    "uieditorpath": "/root/example",
    "hideHiddenFiles": true,
    "exclusionPatterns": ["*test", "./test/*", "./logs"],
    "showdashboard": true,
    "dashboards": [{"name": "Tab Name", "port": 80}, {"name": "Tab Name", "port": 8080}],
    "uilayout": "editor-terminal"
  },
  "backend": {
    "imageid": "ubuntu"
  }
}

Complete Example for index.yaml

---
title: Lab Title
description: Lab Description
difficulty: beginner
time: 5-10 minutes
details:
  steps:
  - title: First Step Title
    text: step1.md
    answer: step1-answer.md
    verify: step1-verify.sh
    verify: step1-solution.sh
    background: run-command-in-background.sh
    foreground: run-command-in-terminal.sh
  - title: Second Step Title
    text: step2.md
  intro:
    text: intro.md
    background: courseBase.sh
    foreground: changecd.sh
  finish:
    text: finish.md
  assets:
    client:
    - file: docker-compose.yml
      target: "~/"
    host01:
    - file: config.yml
      target: "~/"
files:
- app.js
environment:
  uieditorpath: "/root/example"
  hideHiddenFiles: true
  exclusionPatterns:
  - "*test"
  - "./test/*"
  - "./logs"
  showdashboard: true
  dashboards:
  - name: Tab Name
    port: 80
  - name: Tab Name
    port: 8080
  uilayout: editor-terminal
backend:
  imageid: ubuntu