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