# Creating a Custom Environment

⚠️ NOTE: This feature is only available for preexisting Katacoda customers with paid subscriptions. This feature is not supported for any newly created accounts.

A custom environment is an environment created specifically for your organization. This feature is typically used to pre-install large or complex tools, pre-cache Docker images, or generate files that are common across many of your organization's scenarios.

# Base Images

Start with one of the supported base images.

The imageid of the base image will be defined in the file katacoda.yaml in the directory corresponding to your environment.

# Creating a New Environment

Create a new directory called environments in your repository. This will house any custom environments that you define.

Within environments, create a subdirectory for the new environment, such as exampleenv1. Within that subdirectory, create a new directory called build.

At this point, your directory structure should appear as:

└── environments
    └── exampleenv1
        └── build

The build directory will contain your build scripts, prefixed with a number to indicate order. For example:

  • 1_installpackages.sh
  • 2_pulldockerimages.sh
  • 3_pulldemos.sh

You can have as many scripts as you want, and they will execute in the order listed. For clarity, we strongly recommend numbering the file names as above.

In the exampleenv1 directory, create a katacoda.yaml file, and specify the base image ID.

base: 'ubuntu1604'

At this point, your directory structure should appear as:

└── environments
    └── exampleenv1
        ├── build
        │   ├── 1_installpackages.sh
        │   ├── 2_pulldockerimages.sh
        │   └── 3_pulldemos.sh
        └── katacoda.yaml

You can see an example for exampleenv1. In this case, the base image used is Ubuntu 16.04, and the build scripts install additional packages and pull Docker images.

Once you commit and push changes to your repository, you can review the build logs at:


Finally, to use your new environment in a scenario, reference an imageid of <orgname-environmentdirectoryname>. For example, if your organization name is katacoda and the environment's name is exampleenv1, then you'd specify an imageid of katacoda-exampleenv1.

New custom environments are available right away on https://beta.katacoda.com/ for testing purposes. Once finalized, you can request promotion to production via the dashboard.

# Multi-node environments

This is an example of the custom environment for kubernetes 1.16.

Create a directory called kubernetes-cluster-1-16, inside of it, you should have a directory for the master and another directory for the node. Inside of the directories master and node there should be the katacoda.yaml file indicating the base image. The katacoda.yaml file defined as root level is not used at the moment, and it is prepared for future use.

The directory structure should be:

├── kubernetes-cluster-1-16
│   ├── master
│   │   ├── build
│   │   │   └── 1_init.sh
│   │   └── katacoda.yaml
│   └── node
│       ├── build
│       │   └── 1_init.sh
│       └── katacoda.yaml

Note: currently, it is only supported for clusters with 2 nodes and the name of the environment should contain the string -cluster.

For each master and node, create a build directory where you will put your build scripts. As an example, you can see at kubernetes custom environment. In this case, the build script is based on Ubuntu 16,04, to install kompose.

# Triggering a build

To trigger a build, you must first link your Github repo to Katacoda. Once you have done this, images in the environments directory will be built whenever you push a change to the master branch.

# Starting Kubernetes Before User Connects

With a paid subscription and customised environments, it is possible to create a custom image where Kubernetes starts automatically for the user. To enable this, name your environment with a "-running" suffix. (Currently, this works by invoking /opt/launch-kubeadm.sh in the background. Its logs are in /opt/launch-logs. Also, kubeadm join will be invoked on the worker node.)

You may instruct your user to run launch.sh as the first step of the scenario, which will wait until /opt/launch-kubeadm.sh completes in the background.

# Running Commands Before User Connects

With a paid subscription and customised environments, the environment can be can be customised to preboot components, such as certain Containers or Kubernetes Deployment.

To configure the environment create a file called /opt/configure-environment.sh that will be executed when the environment starts.

For example, the following script would start the nginx container in the background when the environment had started.

cat << EOF > /opt/configure-environment.sh
docker run -it -d --name=http -p 80:80 nginx
chmod +x /opt/configure-environment.sh

The cluster's name must end with "-running" to enable this feature.

NOTE: On beta the script will be run when the session starts so may take a few moments to reflect the end results. In production this is optimised away so users don't have to wait.

# VS Code

Katacoda includes our rich editor based on VS Code within our Ubuntu and Kubernetes based environments.

# Deploying VS Code Extensions

Additional extensions can be deployed enabling them to be automatically loaded when the IDE starts. During the build of your custom environment, you can download your required package from the Visual Studio market place and extract the extension into the /opt/.katacodacode/extensions/ directory.

To install the extension you will need to know three items:

1. Unique identifier

To obtain the VS Package URL, first go to the package page on the Marketplace and click Download Extension.

Download VS Package

This will download the VS Package. Within Chrome, you can obtain the URL by right clicking and copying the URL.

Download VS Package Copy Link

Another way is to check the right side of the page under the heading More Info, there is a unique identifier with a format of publisher.extension-name. You will also find this at the end of the URL in the browser, for instance for https://marketplace.visualstudio.com/items?itemName=ms-python.python would be ms-python.python. So the publisher is ms-python and the extension name is python.

2. Publisher

Based on the URL: https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-python/vsextensions/python/2020.5.86806/vspackage

The publisher is after /publishers, so in this case, is ms-python.

Or use the information under the heading More Info mentioned above.

3. Version

This information is part of the URL as well, after the name of the extension https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-python/vsextensions/python/2020.5.86806/vspackage, so in this case, it would be 2020.5.86806. And this also can be found under the heading More Info mentioned above.

Use the appropriate values in the following url to be able to download the vsix file:

For example, the following will deploy the Python VS Code extension.

curl -L https://marketplace.visualstudio.com/_apis/public/gallery/publishers/${publisher}/vsextensions/${extensionname}/${version}/vspackage

cd /tmp && apt-get update -y && apt install libarchive-tools -y # install bsdtar

curl -L https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-python/vsextensions/python/2020.5.86806/vspackage | bsdtar -xvf - extension

mv extension /opt/.katacodacode/extensions/ms-python.python-2020.5.86806

The use of bsdtar is required due to the packaging format of VS Extensions.

Note: The name of the directory for the extension should use the same pattern that when the extension is installed manually <publisher>.<extensionname>-<version>, if not, you will see a message Reload is required.

Check the example custom environment and the example scenario.

# Customing VS Code Options

You can customise the default settings for VS Code by creating a settings.json file as shown below. In this example, the Welcome Page, Auto Save and Minimap are disabled.

mkdir -p /opt/.katacodacode/user-data/User/
cat << VSCODEEOF > /opt/.katacodacode/user-data/User/settings.json
  "workbench.startupEditor": "none", 
  "files.autoSave": "off",
  "editor.minimap.enabled": false,
  "window.autoDetectColorScheme": false,
  "workbench.colorCustomizations": {},
  "workbench.colorTheme": "Default Dark+",
  "editor.semanticHighlighting.enabled": false,
  "editor.tokenColorCustomizations": {
      "semanticHighlighting": true
  "files.exclude": {
    "**/.*": true

# Accessing Build Logs

Once you have pushed your changes to the Git repository linked to your organization account a build will be automatically triggered.

You can view the build logs at https://dashboard.katacoda.com/environments/builds