The index.json File

A lab’s index.json 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.

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. Exit code should be 0 to allow user to proceed.
`background`	Run script in the background of the terminal session.
`foreground`	Run script in the foreground of the terminal.

“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 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.
`showvisualise`	Show Weave Scope tab.
`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

{
  "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",
        "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",
      "credits": "",
      "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"
  }
}