---
myst:
  html_meta:
    "description lang=en": "How to build custom Docker images for Kasm Workspaces and configure them to launch from the user dashboard."
    "keywords": "Kasm, How to, How-to, Custom Images, Docker, Build, Customization"
    "property=og:locale": "en_US"
---
```{title} Building Custom Images
```

# Building Custom Images

The ability to create custom {term}`Workspaces <Workspace>` 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
{doc}`Image Maintenance Process</how_to/image_maintenance>` 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 {ref}`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 {doc}`Default or Core Docker Image <../guide/custom_images>` 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 {code}`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](https://snapcraft.io) and some [FlatPaks](https://flatpak.org/).
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](https://github.com/kasmtech/workspaces-images).

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 {term}`Agent <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:{{ release }}-rolling.
```

```{eval-rst}
.. parsed-literal::

  FROM kasmweb/core-ubuntu-focal:|release|

```

```{note}
It is also possible to base a custom Image on any of the default Images published.
See {doc}`Default Docker Images</guide/custom_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 {doc}`Agent Settings <../guide/agent_settings>` for more details.
```

1. Below is the baseline {code}`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 {code}`Dockerfile` with the following contents.

   ```{eval-rst}
   .. parsed-literal::

     FROM kasmweb/core-ubuntu-focal:|release|
     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

   ```

2. Build the Image.

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

3. 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*.
```

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

```{figure} /images/building_images/image_registration.webp
:align: center
**Register New Image**
```

5. From the Kasm Dashboard click Sublime Text Image.

```{figure} /images/building_images/new_image.webp
:align: center
**New Image Available**
```

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

```{figure} /images/building_images/launch_image.webp
:align: center
**Launch Session**
```

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

```{figure} /images/building_images/hello.png
:align: center
**Running the custom Image**
```

## Installing Software

1. Now it's time to do something more useful. We will update the {code}`Dockerfile` to actually install Sublime Text.

   Update the {code}`Dockerfile` with the following contents.

   ```{eval-rst}
   .. parsed-literal::
     FROM kasmweb/core-ubuntu-focal:|release|
     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 {code}`.desktop` file in {code}`/usr/share/applications`.
   This file can often be copied without modification to the desktop {code}`$HOME/Desktop/`. It is important to mark the file as executable and ensure the ownership
   is changed to user and group {code}`1000`
   ```

   **Reference:**

   - <https://www.sublimetext.com/docs/3/linux_repositories.html>

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

```{figure} /images/building_images/sublime_1.png
:align: center
**Sublime Text is Installed**
```

## Custom Startup

1. Next we will utilize the {code}`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 ({code}`1000`) context when the
   session starts. Utilize the built-in command {code}`/usr/bin/desktop_ready` to ensure Sublime Text starts after the
   Kasm desktop environment.

   Update the {code}`Dockerfile` with the following contents.

   ```{eval-rst}
   .. parsed-literal::
     FROM kasmweb/core-ubuntu-focal:|release|
     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

   ```

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

```{figure} /images/building_images/sublime_2.png
:align: center
**Sublime Text Started Automatically**
```

## Desktop Background

1. The background can be changed by overwriting the {code}`/usr/share/backgrounds/bg_default.png` file.

   Update the {code}`Dockerfile` with the following contents.

   ```{eval-rst}
   .. parsed-literal::
     FROM kasmweb/core-ubuntu-focal:|release|
     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

   ```

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

```{figure} /images/building_images/background.png
:align: center
**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.

1. Login to the docker container registry. You will be prompted for a username and password. GitLab provides the ability
   to create [Personal Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
   with permissions that are limited to read and/or write permissions to the registry.

   ```bash
   sudo docker login registry.gitlab.com
   ```

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

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

3. Push the image to the registry

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

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

```{figure} /images/building_images/registry_image.webp
:align: center
**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.

```{figure} /images/launch_config/launch_config_example_dash-1.png
:align: center
**Launch Config Form**
```

See {ref}`launch-config` 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 {doc}`Persistent Profiles <../guide/persistent_data/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](https://github.com/kasmtech/workspaces-core-images/blob/develop/src/common/startup_scripts/kasm_default_profile.sh)

## 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](https://github.com/kasmtech/workspaces-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

```Json
{"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 {doc}`VPN Sidecar Containers <vpn_sidecar/vpn_sidecar>`.