Building Custom Images

The ability to create custom Workspaces is a powerful feature of the Kasm framework. Administrators may choose to maintain and automatically deploy always up-to-date Images to the Kasm deployment with no user downtime. See Image Maintenance Process for more details.

While the build process in this guide is the preferred method for creating robust, sustainable and highly automated images, administrators may also wish to experiment with the Create Image from Session feature, which provides a quick and convenient way to capture the state of an active session if manual configuration is desired.

Administrators will create Docker Images that import from an existing Default or Core Docker Image published by the Kasm Technologies team. The Core Docker images contain the minimal set of configurations that is necessary for the Docker images to work within the platform.

The kasmweb/core-ubuntu-focal image is the preferred core image and is based on Ubuntu 20.04 LTS. Generally speaking most programs that can be installed on Ubuntu can be installed inside this image. The exception are programs that come delivered as containers themselves such as Snaps and some FlatPaks. Administrators will need working knowledge of Docker and scripting to add custom software and configurations to the Docker images.

A Git repository with several example Dockerfiles that demonstrate how to build full desktop or single application images is available on GitHub.

In this guide we will walk through the basic steps for creating a custom Image. These steps can be conducted on the server with the Kasm Agent installed.

Important

The Kasm team publishes new editions of the core image at every release cycle. The Kasm team also maintains rolling updates for all published images, we would recommend basing custom images against a rolling tag on a scheduled build so that the custom image will get regular program and security updates. Be sure to build your image based on the appropriate tag for your deployed Kasm version for example kasmweb/core-ubuntu-focal:1.16.1-rolling-daily or kasmweb/core-ubuntu-focal:1.16.1-rolling-weekly

FROM kasmweb/core-ubuntu-focal:1.16.1

Note

It is also possible to base a custom Image on any of the default Images published. See Default Docker Images for a list.

Basic Build

Tip

If performing a build directly on the Kasm Workspaces server or Agent, disable Automatically Prune Images for the applicable Agent. See Agent Settings for more details.

Below is the baseline Dockerfile used to create a custom Kasm Image. There is a pre-defined sections where customizations are to be added. The statements before and after this section should not be modified. In this example a single customization is added: an file named hello.txt is created on the desktop.

Create a file named Dockerfile with the following contents.

FROM kasmweb/core-ubuntu-focal:1.16.1
USER root

ENV HOME /home/kasm-default-profile
ENV STARTUPDIR /dockerstartup
ENV INST_SCRIPTS $STARTUPDIR/install
WORKDIR $HOME

######### Customize Container Here ###########


RUN touch $HOME/Desktop/hello.txt


######### End Customizations ###########

RUN chown 1000:0 $HOME
RUN $STARTUPDIR/set_user_permission.sh $HOME

ENV HOME /home/kasm-user
WORKDIR $HOME
RUN mkdir -p $HOME && chown -R 1000:0 $HOME

USER 1000

Build the Image.

sudo docker build -t sublime-text:example -f Dockerfile .

Log into the Kasm UI as an administrator and register a new Workspace by selecting the Workspaces panel and clicking on Add Workspace (It is also possible using the arrow menu to clone the configuration of an existing workspace)

Tip

Kasm Workspaces does not assume the tag latest as many other docker tools do. This is because docker images from older versions my not be compatible with newer versions, and reduces the benefit of a latest tag. The Kasm team recommends using a tag that reflects the version of the core image being used as a base. Kasm workspaces expects an explicit tag be specified in the Workspace configuration for Docker Image.

When finished editing details of the workspace click Save to create the new workspace.

../_images/image_registration.webp — **Register New Image**

From the Kasm Dashboard click Sublime Text Image.

../_images/new_image.webp — **New Image Available**

There will be a new pop up in the UI that has a LAUNCH SESSION button, click it to launch the Kasm session.

../_images/launch_image.webp — **Launch Session**

A new session is created with the hello.txt file we created.

../_images/hello.png — **Running the custom Image**

Installing Software

Now it’s time to do something more useful. We will update the Dockerfile to actually install Sublime Text.

Update the Dockerfile with the following contents.

FROM kasmweb/core-ubuntu-focal:1.16.1
USER root

ENV HOME /home/kasm-default-profile
ENV STARTUPDIR /dockerstartup
ENV INST_SCRIPTS $STARTUPDIR/install
WORKDIR $HOME

######### Customize Container Here ###########

RUN  wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | apt-key add - \
    && apt-get update \
    && apt-get install -y apt-transport-https \
    && echo "deb https://download.sublimetext.com/ apt/stable/" |  tee /etc/apt/sources.list.d/sublime-text.list \
    && apt-get update \
    && apt-get install sublime-text \
    && cp /usr/share/applications/sublime_text.desktop $HOME/Desktop/ \
    && chmod +x $HOME/Desktop/sublime_text.desktop \
    && chown 1000:1000 $HOME/Desktop/sublime_text.desktop


######### End Customizations ###########

RUN chown 1000:0 $HOME
RUN $STARTUPDIR/set_user_permission.sh $HOME

ENV HOME /home/kasm-user
WORKDIR $HOME
RUN mkdir -p $HOME && chown -R 1000:0 $HOME

USER 1000

Note

Creating desktop icons is a common need. This example highlights how applications , when installed often place a .desktop file in /usr/share/applications. This file can often be copied without modification to the desktop $HOME/Desktop/. It is important to mark the file as executable and ensure the ownership is changed to user and group 1000

Reference:

https://www.sublimetext.com/docs/3/linux_repositories.html

Rebuild the Image and create a new session and verify Sublime Text is installed and an icon is present on the desktop.

../_images/sublime_1.png — **Sublime Text is Installed**

Custom Startup

Next we will utilize the custom_startup.sh interface point to launch Sublime text when the session starts. Create the script and mark it executable. This script will run in the standard user (1000) context when the session starts. Utilize the built-in command /usr/bin/desktop_ready to ensure Sublime Text starts after the Kasm desktop environment.

Update the Dockerfile with the following contents.

FROM kasmweb/core-ubuntu-focal:1.16.1
USER root

ENV HOME /home/kasm-default-profile
ENV STARTUPDIR /dockerstartup
ENV INST_SCRIPTS $STARTUPDIR/install
WORKDIR $HOME

######### Customize Container Here ###########

RUN  wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | apt-key add - \
    && apt-get update \
    && apt-get install -y apt-transport-https \
    && echo "deb https://download.sublimetext.com/ apt/stable/" |  tee /etc/apt/sources.list.d/sublime-text.list \
    && apt-get update \
    && apt-get install sublime-text \
    && cp /usr/share/applications/sublime_text.desktop $HOME/Desktop/ \
    && chmod +x $HOME/Desktop/sublime_text.desktop \
    && chown 1000:1000 $HOME/Desktop/sublime_text.desktop

RUN echo "/usr/bin/desktop_ready && /opt/sublime_text/sublime_text &" > $STARTUPDIR/custom_startup.sh \
&& chmod +x $STARTUPDIR/custom_startup.sh


######### End Customizations ###########

RUN chown 1000:0 $HOME
RUN $STARTUPDIR/set_user_permission.sh $HOME

ENV HOME /home/kasm-user
WORKDIR $HOME
RUN mkdir -p $HOME && chown -R 1000:0 $HOME

USER 1000

Rebuild the Image and create a new session. Sublime Text should start automatically.

../_images/sublime_2.png — **Sublime Text Started Automatically**

Desktop Background

The background can be changed by overwriting the /usr/share/backgrounds/bg_default.png file.

Update the Dockerfile with the following contents.

FROM kasmweb/core-ubuntu-focal:1.16.1
USER root

ENV HOME /home/kasm-default-profile
ENV STARTUPDIR /dockerstartup
ENV INST_SCRIPTS $STARTUPDIR/install
WORKDIR $HOME

######### Customize Container Here ###########

RUN  wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | apt-key add - \
    && apt-get update \
    && apt-get install -y apt-transport-https \
    && echo "deb https://download.sublimetext.com/ apt/stable/" |  tee /etc/apt/sources.list.d/sublime-text.list \
    && apt-get update \
    && apt-get install sublime-text \
    && cp /usr/share/applications/sublime_text.desktop $HOME/Desktop/ \
    && chmod +x $HOME/Desktop/sublime_text.desktop \
    && chown 1000:1000 $HOME/Desktop/sublime_text.desktop

RUN echo "/usr/bin/desktop_ready && /opt/sublime_text/sublime_text &" > $STARTUPDIR/custom_startup.sh \
&& chmod +x $STARTUPDIR/custom_startup.sh

RUN wget https://cdn.hipwallpaper.com/i/92/9/0Ts6mr.png -O /usr/share/backgrounds/bg_default.png

######### End Customizations ###########

RUN chown 1000:0 $HOME
RUN $STARTUPDIR/set_user_permission.sh $HOME

ENV HOME /home/kasm-user
WORKDIR $HOME
RUN mkdir -p $HOME && chown -R 1000:0 $HOME

USER 1000

Rebuild the image and create a new session. Sublime Text should start automatically.

../_images/background.png — **Custom Desktop Background**

Push to Registry

To simplify Image management, it is recommended to utilize a docker container registry. This example will utilize a container registry that is provided by GitLab.

Login to the docker container registry. You will be prompted for a username and password. GitLab provides the ability to create Personal Access Tokens with permissions that are limited to read and/or write permissions to the registry.
```
sudo docker login registry.gitlab.com
```

Build the image, using the registry location as part of the image name.

sudo docker build -t registry.gitlab.com/my-company/my-project/sublime-text:example -f Dockerfile .

Push the image to the registry

sudo docker push registry.gitlab.com/my-company/my-project/sublime-text:example

Register the image in Kasm by creating a new Workspace pointing to the docker image. Enter the gitlab username in the Docker Registry Username field and the Gitlab password or access token under the Docker Registry Password field

../_images/registry_image.webp — **Using a Docker Container Registry**

Custom Launch Forms

It is also possible for administrators to present custom forms to users when a workspace is launched. This may be helpful when creating more advanced turnkey solutions for a given workspace. In the following example, a form element is presented to get an authentication key for a Tailscale VPN connection. The workspace container will then use this key to establish the connection.

../_images/launch_config_example_dash-1.png — **Launch Config Form**

See Workspace Launch Forms for more details.

Understanding `kasm-default-profile`

In the Dockerfile template used above, the pre-customization steps set the HOME environment variable to /home/kasm-default-profile.

ENV HOME /home/kasm-default-profile

Then in the post-customizations steps, the HOME directory is set to /home/kasm-user which eventually is the profile directory used when the container starts.

ENV HOME /home/kasm-user

This process is done to support the Persistent Profiles feature. When a container is not using persistent profiles or the first time a user creates a session when persistent profiles is enabled, the /home/kasm-user directory will be empty. When the container starts, if the path /home/kasm-user is empty, it will copy the default profile from /home/kasm-default-profile to /home/kasm-user. If persistent profiles are enabled, the /home/kasm-user directory will not be empty for the user’s next session.

The copy script resides within the Core images and can be adjusted if necessary. It is visible in the workspaces-core-images Github Repo

General Docker Images

Kasm Workspaces is intended primarily for UI streaming containers, however, Workspaces can also orchestrate containers using any image. Images that are not based on one of the Kasm maintained core images will be incompatible with some features.

Web Filtering
URL Categorization
Connecting to container through the UI

By default, Workspaces applies a restart policy to containers of ‘unless-stopped’, which means the container is automatically restarted unless it is manually stopped. This may or may not be desired. To launch containers that perform a task and exit, the default restart policy must be overridden.

Workspaces will also run every container as USER 1000 unless overridden.

In the Workspaces Admin UI, navigate to Workspaces, edit the desired Workspace and in the Docker Run Config Override (JSON) field, set the restart policy to ‘on-failure’ and optionally the container user as shown here

{"restart_policy":{"Name":"on-failure","MaximumRetryCount":5}, "user": "root"}

With this policy applied, when a user creates an instance of this image, it will be automatically removed when the container is finished running.

Routing Image traffic through a VPN

In order to route an image’s traffic through a sidecar VPN container please checkout VPN Sidecar Containers.

Building Custom Images

Basic Build

Installing Software

Custom Startup

Desktop Background

Push to Registry

Custom Launch Forms

Understanding kasm-default-profile

General Docker Images

Routing Image traffic through a VPN

Understanding `kasm-default-profile`