# Creating Custom Environment

A custom environment is an environment that you can create for your organization, based on one of the available katacoda base images. It is commonly used to pre-cached docker images, installing tools, and creating files that are common across all the scenarios.

NOTE: This is only available with a Katacoda Subscription.

# Base images

These are the base images available at the moment:

Environment Implementation Notes ImageID
Ubuntu 18.04 Docker installed and running ubuntu1804
Centos 7 Docker installed and running centos7
Kubernetes Cluster 1.16 (Ubuntu) 2 nodes with kubeadm installed, nothing running. Based on Ubuntu 16.04. kubernetes-master-ubuntu1604-1-16 and kubernetes-node-ubuntu1604-1-16
Kubernetes Cluster 1.18 (Ubuntu) 2 nodes with kubeadm installed, nothing running. Based on Ubuntu 18.04. kubernetes-master-ubuntu1804-1-18 and kubernetes-node-ubuntu1804-1-18
Kubernetes Cluster 1.16 (CentOS) 2 nodes with kubeadm installed, nothing running. Based on CentOS 7. kubernetes-master-centos7-1-16 and kubernetes-node-centos7-1-16
Minikube 1 node with minikube 1.8.1, nothing running. Based on Ubuntu 18.04. minikube

The id 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 directory called environments in the repository. Within there you can have a environment, such as exampleenv1. Within the directory, create a new directory called build. This 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 order as listed, so we recommend to number it.

Inside of the directory corresponding to your environment, create a katacoda.yaml file, and define the base image.

base: 'ubuntu1604'

The directory structure should be:

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

You can see an example for exampleenv1. In this case, the build scripts are based on Ubuntu 16,04, install additional packages and pull Docker Images.

Once you commit and push the changes, you can see the logs at https://dashboard.katacoda.com/environments/builds/

To use the environment, the imageid name would be <orgname-environmentdirectoryname>, for example if organization is katacoda, the environment will have the id katacoda-exampleenv1. The custom environments are available on https://beta.katacoda.com/ for testing. Once happy, you can request the promotion 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 pacakge from the Visual Studio market place and extract the extension into the /opt/.katacodacode/extensions/ directory.

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

apt install bsdtar -y

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/mspython

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

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

# 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