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.

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.12.0-rolling.

FROM kasmweb/core-ubuntu-focal:1.12.0

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.12.0
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 three dot menu to clone the configuration of an existing workspace)
When finished editing details of the workspace click Submit to create the new workspace.

Register New Image
From the Kasm Dashboard click Sublime Text Image.

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.

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

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.12.0
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.

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.12.0
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.

Sublime Text Started Automatically

Desktop Background

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

Update the Dockerfile with the following contents.

FROM kasmweb/core-ubuntu-focal:1.12.0
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/extra/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.

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

Using a Docker Container Registry

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 performed a task and exit, the default restart policy must be 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’ as shown here.

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

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.