Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,20 +59,20 @@ The architectures supported by this image are:

This container uses [Docker in Docker](https://www.docker.com/blog/docker-can-now-run-within-docker/) and requires being run in `privileged` mode. This container also requires an initial setup that runs on port 3000.

**Unlike other containers the web interface port (default 443) needs to be set for the env variable `KASM_PORT` and both the inside and outside port IE for 4443 `KASM_PORT=4443` `-p 4443:4443`**
### First-run setup

**Unraid users due to the DinD storage layer `/opt/` should be mounted directly to a disk IE `/mnt/disk1/appdata/path` or optimally with a cache disk at `/mnt/cache/appdata/path`**
Access the installation wizard at https://127.0.0.1:3000 and follow the instructions there. If using our example run/compose the setup page is only bound to 127.0.0.1.

Access the installation wizard at https://`your ip`:3000 and follow the instructions there. Once setup is complete access https://`your ip`:443 and login with the credentials you entered during setup. The default users are:
Once setup is complete access https://`<hostip>`:443 and login with the credentials you entered during setup. The default users are:

* admin@kasm.local
* user@kasm.local

Currently Synology systems are not supported due to them blocking CPU scheduling in their Kernel.
**Never expose the installation wizard to the internet and ensure `KASM_SETUP` is set to `false` during normal use.**

### Upgrading KASM

In order to upgrade Kasm, first make sure you are using the latest docker image, and then perform the in app update from the installation wizard. Docker image update and recreation of container alone won't upgrade Kasm.
In order to upgrade Kasm, first make sure you are using the latest docker image, and then set `KASM_SETUP=true` to allow you to perform the update from the installation wizard. Docker image update and recreation of container alone won't upgrade Kasm.

Following the upgrade, you will need to update any workspace image tags to match the new version.

Expand All @@ -94,6 +94,12 @@ In order to use persistant profiles in Workspaces you will need to mount in a fo

A sample for [SWAG](https://github.com/linuxserver/docker-swag) can be found [here](https://raw.githubusercontent.com/linuxserver/reverse-proxy-confs/master/kasm.subdomain.conf.sample). Post installation you will need to modify the "Proxy Port" setting under the default zone to 0 as outlined [here](https://docs.kasm.com/docs/latest/how-to/reverse_proxy/index.html#update-zones) to launch Workspaces sessions.

### Additional notes

* **The web interface port (default 443) needs to match the env variable `KASM_PORT` and both the inside and outside port i.e. to use port 4443, set `KASM_PORT=4443` `-p 4443:4443`**
* **Unraid users due to the DinD storage layer `/opt/` should be mounted directly to a disk IE `/mnt/disk1/appdata/path` or optimally with a cache disk at `/mnt/cache/appdata/path`**
* Currently Synology systems are not supported due to them blocking CPU scheduling in their Kernel.

### Strict reverse proxies

This image uses a self-signed certificate by default. This naturally means the scheme is `https`.
Expand All @@ -116,9 +122,10 @@ services:
container_name: kasm
privileged: true
security_opt:
- apparmor:rootlesskit #optional
- apparmor:runc #optional
environment:
- KASM_PORT=443
- KASM_SETUP=false
- DOCKER_HUB_USERNAME=USER #optional
- DOCKER_HUB_PASSWORD=PASS #optional
- DOCKER_MTU=1500 #optional
Expand All @@ -128,7 +135,7 @@ services:
- /dev/input:/dev/input #optional
- /run/udev/data:/run/udev/data #optional
ports:
- 3000:3000
- 127.0.0.1:3000:3000
- 443:443
stop_grace_period: "90s" #optional
restart: unless-stopped
Expand All @@ -140,12 +147,13 @@ services:
docker run -d \
--name=kasm \
--privileged \
--security-opt apparmor=rootlesskit `#optional` \
--security-opt apparmor=runc `#optional` \
-e KASM_PORT=443 \
-e KASM_SETUP=false \
-e DOCKER_HUB_USERNAME=USER `#optional` \
-e DOCKER_HUB_PASSWORD=PASS `#optional` \
-e DOCKER_MTU=1500 `#optional` \
-p 3000:3000 \
-p 127.0.0.1:3000:3000 \
-p 443:443 \
-v /path/to/kasm/data:/opt \
-v /path/to/kasm/profiles:/profiles `#optional` \
Expand All @@ -162,9 +170,10 @@ Containers are configured using parameters passed at runtime (such as those abov

| Parameter | Function |
| :----: | --- |
| `-p 3000:3000` | Kasm Installation wizard. (https) |
| `-p 127.0.0.1:3000:3000` | Kasm Installation wizard. (https) |
| `-p 443:443` | Kasm Workspaces interface. (https) |
| `-e KASM_PORT=443` | Specify the port you bind to the outside for Kasm Workspaces. |
| `-e KASM_SETUP=false` | Set to `true` to enable the Kasm setup page, *first-run setup is always enabled*. |
| `-e DOCKER_HUB_USERNAME=USER` | Optionally specify a DockerHub Username to pull private images. |
| `-e DOCKER_HUB_PASSWORD=PASS` | Optionally specify a DockerHub password to pull private images. |
| `-e DOCKER_MTU=1500` | Optionally specify the mtu options passed to dockerd. |
Expand All @@ -173,7 +182,7 @@ Containers are configured using parameters passed at runtime (such as those abov
| `-v /dev/input` | Optional for gamepad support. |
| `-v /run/udev/data` | Optional for gamepad support. |
| `--stop-timeout=` | Increase container shutdown delay to give Kasm services time to stop cleanly. |
| `--security-opt apparmor=rootlesskit` | Some hosts require this on top of privileged for namespacing to work properly inside the DinD layer. |
| `--security-opt apparmor=runc` | Some hosts require this on top of privileged for namespacing to work properly inside the DinD layer. |

## Environment variables from files (Docker secrets)

Expand Down Expand Up @@ -319,6 +328,7 @@ Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64

## Versions

* **15.11.26:** - Add `KASM_SETUP` toggle, default to disabling install wizard after first-run.
* **07.08.26:** - Fix NVIDIA passthrough to Workspace containers by generating a CDI specification inside the DinD layer.
* **04.08.26:** - Give kasm_manager a healthcheck start period so a cold start does not leave kasm_proxy created but never started.
* **16.04.26:** - Update for 1.18.1 release. Use rolling service images. Bump docker to v29.
Expand Down
23 changes: 16 additions & 7 deletions readme-vars.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,13 @@ param_usage_include_net: false
param_usage_include_env: true
param_env_vars:
- {env_var: "KASM_PORT", env_value: "443", desc: "Specify the port you bind to the outside for Kasm Workspaces."}
- {env_var: "KASM_SETUP", env_value: "false", desc: "Set to `true` to enable the Kasm setup page, *first-run setup is always enabled*."}
param_usage_include_vols: true
param_volumes:
- {vol_path: "/opt", vol_host_path: "/path/to/{{ project_name }}/data", desc: "Docker and installation storage."}
param_usage_include_ports: true
param_ports:
- {external_port: "3000", internal_port: "3000", port_desc: "Kasm Installation wizard. (https)"}
- {external_port: "127.0.0.1:3000", internal_port: "3000", port_desc: "Kasm Installation wizard. (https)"}
- {external_port: "443", internal_port: "443", port_desc: "Kasm Workspaces interface. (https)"}
# optional container parameters
opt_param_usage_include_env: true
Expand All @@ -41,7 +42,7 @@ opt_param_volumes:
- {vol_path: "/run/udev/data", vol_host_path: "/run/udev/data", desc: "Optional for gamepad support."}
opt_security_opt_param: true
opt_security_opt_param_vars:
- {run_var: "apparmor=rootlesskit", compose_var: "apparmor:rootlesskit", desc: "Some hosts require this on top of privileged for namespacing to work properly inside the DinD layer."}
- {run_var: "apparmor=runc", compose_var: "apparmor:runc", desc: "Some hosts require this on top of privileged for namespacing to work properly inside the DinD layer."}
opt_custom_params:
- {name: "stop-timeout", name_compose: "stop_grace_period", value: "90s", desc: "Increase container shutdown delay to give Kasm services time to stop cleanly."}
unraid_template: false
Expand All @@ -51,20 +52,20 @@ app_setup_block_enabled: true
app_setup_block: |
This container uses [Docker in Docker](https://www.docker.com/blog/docker-can-now-run-within-docker/) and requires being run in `privileged` mode. This container also requires an initial setup that runs on port 3000.

**Unlike other containers the web interface port (default 443) needs to be set for the env variable `KASM_PORT` and both the inside and outside port IE for 4443 `KASM_PORT=4443` `-p 4443:4443`**
### First-run setup

**Unraid users due to the DinD storage layer `/opt/` should be mounted directly to a disk IE `/mnt/disk1/appdata/path` or optimally with a cache disk at `/mnt/cache/appdata/path`**
Access the install wizard at https://<hostip>:3000 and follow the instructions there. In our example run/compose the install wizard is only bound to 127.0.0.1, so if you need to access it over the network this will need changing.

Access the installation wizard at https://`your ip`:3000 and follow the instructions there. Once setup is complete access https://`your ip`:443 and login with the credentials you entered during setup. The default users are:
Once setup is complete access https://<hostip>:443 and login with the credentials you entered during setup. The default users are:

* admin@kasm.local
* user@kasm.local

Currently Synology systems are not supported due to them blocking CPU scheduling in their Kernel.
**Never expose the install wizard to the internet and ensure `KASM_SETUP` is set to `false` during normal use.**

### Upgrading KASM

In order to upgrade Kasm, first make sure you are using the latest docker image, and then perform the in app update from the installation wizard. Docker image update and recreation of container alone won't upgrade Kasm.
In order to upgrade Kasm, first make sure you are using the latest docker image, and then set `KASM_SETUP=true` to allow you to perform the update from the installation wizard. Docker image update and recreation of container alone won't upgrade Kasm.

Following the upgrade, you will need to update any workspace image tags to match the new version.

Expand All @@ -85,6 +86,13 @@ app_setup_block: |
### Reverse proxy

A sample for [SWAG](https://github.com/linuxserver/docker-swag) can be found [here](https://raw.githubusercontent.com/linuxserver/reverse-proxy-confs/master/kasm.subdomain.conf.sample). Post installation you will need to modify the "Proxy Port" setting under the default zone to 0 as outlined [here](https://docs.kasm.com/docs/latest/how-to/reverse_proxy/index.html#update-zones) to launch Workspaces sessions.

### Additional notes

* **The web interface port (default 443) needs to match the env variable `KASM_PORT` and both the inside and outside port i.e. to use port 4443, set `KASM_PORT=4443` `-p 4443:4443`**
* **Unraid users due to the DinD storage layer `/opt/` should be mounted directly to a disk IE `/mnt/disk1/appdata/path` or optimally with a cache disk at `/mnt/cache/appdata/path`**
* Currently Synology systems are not supported due to them blocking CPU scheduling in their Kernel.

# init diagram
init_diagram: |
"kasm:latest": {
Expand Down Expand Up @@ -132,6 +140,7 @@ init_diagram: |
"kasm:latest" <- Base Images
# changelog
changelogs:
- {date: "15.11.26:", desc: "Add `KASM_SETUP` toggle, default to disabling install wizard after first-run."}
- {date: "07.08.26:", desc: "Fix NVIDIA passthrough to Workspace containers by generating a CDI specification inside the DinD layer."}
- {date: "04.08.26:", desc: "Give kasm_manager a healthcheck start period so a cold start does not leave kasm_proxy created but never started."}
- {date: "16.04.26:", desc: "Update for 1.18.1 release. Use rolling service images. Bump docker to v29."}
Expand Down
1 change: 0 additions & 1 deletion root/etc/s6-overlay/s6-rc.d/init-config-kasm/up

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,11 @@ if [[ -S /var/run/docker.sock ]]; then
rm -f /var/run/docker.sock
fi

# Clean up old containerd pid
if [[ -f /var/run/docker/containerd/containerd.pid ]]; then
rm -f /var/run/docker/containerd/containerd.pid
fi

# The NVIDIA container toolkit on the host injects the driver into this container,
# but nothing carries it over to the Workspace containers started inside the DinD
# layer. Describe the devices and driver we were handed in a CDI specification, so
Expand Down
1 change: 1 addition & 0 deletions root/etc/s6-overlay/s6-rc.d/init-kasm-config/up
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/etc/s6-overlay/s6-rc.d/init-kasm-config/run
11 changes: 7 additions & 4 deletions root/etc/s6-overlay/s6-rc.d/svc-kasm-wizard/run
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@

# Wait for docker to be up
while [[ ! -S /var/run/docker.sock ]]; do
sleep 1
sleep 1
done

# Don't do anything if wizard is disabled
if [[ -f "/opt/NO_WIZARD" ]]; then
sleep infinity
# Don't do anything if Kasm is installed and/or wizard is disabled
if [[ -L /opt/kasm/current ]]; then
if [[ "${KASM_SETUP}" != 'true' ]] || [[ -f "/opt/NO_WIZARD" ]]; then
echo "KASM_SETUP is not set to 'true' and Kasm has been installed, disabling install wizard"
sleep infinity
fi
fi

cd /wizard || exit 1
Expand Down
13 changes: 13 additions & 0 deletions root/etc/s6-overlay/s6-rc.d/svc-wizard-watchdog/run
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
#!/usr/bin/with-contenv bash

if [[ ! -L /opt/kasm/current ]]; then
while ! pgrep -f /kasm_release/install.sh &>/dev/null; do
sleep 5
done

while pgrep -f /kasm_release/install.sh &>/dev/null; do
sleep 5
done

pkill --signal SIGTERM -f '/usr/bin/node index.js'
fi
1 change: 1 addition & 0 deletions root/etc/s6-overlay/s6-rc.d/svc-wizard-watchdog/type
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
oneshot
1 change: 1 addition & 0 deletions root/etc/s6-overlay/s6-rc.d/svc-wizard-watchdog/up
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/etc/s6-overlay/s6-rc.d/svc-wizard-watchdog/run
Empty file.
Empty file.
Loading