Repository Structure

Each lab is tied to a directory containing an index.json manifest file (along with any step, asset, and setup files). These directories are then shown as labs (formerly “scenarios”) on your Katacoda profile page. If you’re an O’Reilly author, we will have setup the repo and katacoda profile for you.

Basic Repository Structure

Directories for labs should be lowercase and must not contain spaces. The most common case is one in which your labs are placed into directories in the root of the repository, e.g.:

example-labs-repo.git
├── katacoda.yaml  # used to set the profile page to "private"
├── README.md
├── scenario-one
│   ├── assets
│   │   ├── example.js
│   │   └── picture1.png
│   ├── finish.md
│   ├── foreground.sh
│   ├── index.json
│   ├── intro.md
│   ├── step1.md
│   ├── step2.md
│   ├── step3.md
│   └── step4.md
├── create-scenario-101
│   ├── assets
│   │   ├── example.js
│   │   └── picture1.png
│   ├── background.sh
│   ├── finish.md
│   ├── foreground.sh
│   ├── index.yaml
│   ├── intro.md
│   ├── step1.md
│   ├── step2.md
│   ├── step3.md

IMPORTANT: If your repository is missing the katacoda.yaml file, there is a high probability that there will be errors embedding your labs inside the O’Reilly learning platform.

IMPORTANT: Each lab must have only one index file, either index.json or index.yaml.

Course Repository Structure

Labs can be grouped by a common subject, and this is represented with a course. A course is defined by creating a pathway file. The pathway defines which scenarios should be included in the course and the order to display them.

IMPORTANT: Courses are often helpful for organizing multiple sets of labs, but at the time of writing they will not appear as “courses” on the learning platform. Courses should therefore be thought of as an authoring organizational tool rather than a true learning path.

The pathway file must be named with the same name of the directory, followed by the suffix -pathway.json.

Important: Your labs will not appear on the course page if you do not have the “-pathway” suffix on the course JSON file.

For example, in the following example we have a course showing some of the available layouts; the course is uilayouts, we have the scenarios uilayout-editor-terminal, uilayout-iframe, uilayout-terminal, etc., and the pathway file to define the course is uilayouts-pathway.json:

scenario-examples.git
├── uilayouts
│   ├── uilayout-editor-terminal
│   │   ├── index.json
│   │   ├── intro.md
│   │   ├── setup.sh
│   │   └── step1.md
│   ├── uilayout-iframe
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-iframe
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-iframe-split
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-terminal
│   │   ├── index.json
│   │   └── step1.md
│   └── uilayout-terminal-with-vscode
│       ├── index.json
│       └── step1.md
├── uilayouts-pathway.json

Pathway files must be in JSON format. The content of uilayouts-pathway.json is as follows:

{
  "title": "Katacoda UI Layouts Example",
  "description": "Example of different Katacoda UI Layouts. Also, an example of creating a Katacoda Course!",
  "icon": "fa-katacoda",
  "courses": 
  [
    {
      "course_id": "uilayout-terminal",
      "title": "Scenario with Terminal UI",
      "description": "Katacoda Scenario Example"
    },
    {
      "course_id": "uilayout-editor-terminal",
      "title": "Scenario with Editor Terminal UI",
      "description": "Katacoda Scenario Example"
    },
    {
      "course_id": "uilayout-terminal-with-vscode",
      "title": "Scenario with Terminal and VS Code UI",
      "description": "Katacoda Scenario Example"
    }
    ...
  ]
}

Pathway Parameters

The pathway parameters are as follows:

Courses Parameters

The course parameters are as follows:

Moving Katacoda Content To Sub-Directory

Note: We recommend keeping all lab content (save courses) at the root-level of your repository. The following information is provided primarily for historical/legacy knowledge sharing and troubleshooting.

By default, the labs content is located at the top-level of a Git repository.

In the root of the repository, create a file called katacoda.yaml. The contents of the YAML content should have the element scenario_root that points to the directory in the repository that has the lab content. For example:

---
scenario_root: subdirectory/storing/katacoda/content

The structure of the content within this directory should then be the same as above.