Deployment Overview of Kasm Workspaces on Server¶

Prerequisites and Basic Requirements¶

The deployment of Kasm Workspaces requires a Linux server environment. Based on the configuration data, the following prerequisites must be met:

• Operating System: Ubuntu 22.04 (Jammy) or RHEL-based distributions.
• Privileges: Root access or sudo privileges are required to install packages, manage Docker, and configure system services.
• Network: The server must have a public hostname configured (e.g., prefix-server_id.zone) to facilitate SSL certificate issuance.
• Ports: The application utilizes port 3000 for the web interface and a configurable port defined by the KASM_PORT environment variable.
• Storage: Sufficient disk space is required for the application, container images, and user profiles. The installation script configures a swap size of 8192 MB.

File and Directory Structure¶

The application organizes its files and data in specific directories on the host system:

• Installation Directory: /opt/kasm
  • Contains the main application binaries and configuration.
  • Current version symlink: /opt/kasm/current
  • Certificates location: /opt/kasm/current/certs
• Data Storage (RHEL/Container Mode):
  • Main data directory: /data
  • Kasm application data: /data/kasm
  • User profiles: /data/kasm/profiles
• Docker Configuration:
  • Daemon configuration file: /etc/docker/daemon.json
• SSL Certificates:
  • Let's Encrypt certificates are stored in /etc/letsencrypt/live/<domain>/ and copied to the Kasm certificate directory.

Application Installation Process¶

The installation process differs slightly depending on the operating system and deployment method.

Ubuntu/Debian Installation¶

On Ubuntu 22.04 systems, the installation involves downloading a specific release archive and executing an installer script.

1. Package Updates: The system packages are updated using apt.
2. Docker Version Management: Docker CE is installed or downgraded to version 5:28.5.2-1~ubuntu.22.04~jammy to ensure compatibility. The packages docker-ce and docker-ce-cli are held to prevent automatic upgrades.
3. Archive Download: The installation archive is downloaded from https://kasm-static-content.s3.amazonaws.com/kasm_release_1.17.0.bbc15c.tar.gz to /root/.
4. Extraction: The archive is extracted to /root/kasm_release.
5. Script Execution: The install.sh script is executed with the following parameters:
   • --admin-password: Sets the administrator password.
   • --user-password: Sets the default user password.
   • --public-hostname: Defines the public domain name for the instance.
   • --accept-eula: Automatically accepts the End User License Agreement.
   • --no-images: Skips the download of container images during initial setup.
   • --no-check-ports: Skips port availability checks.
   • --no-check-disk: Skips disk space checks.
   • --swap-size 8192: Configures the swap size to 8192 MB.

RHEL/Container Installation¶

On RHEL-based systems, the application is deployed directly as a Docker container using the lscr.io/linuxserver/kasm:latest image.

Docker Containers and Their Deployment¶

Kasm Workspaces runs within a Docker container. The deployment configuration includes specific environment variables, volume mounts, and port mappings.

Container Configuration¶

The container is named kasm and runs with the following settings:

• Image: lscr.io/linuxserver/kasm:latest
• Privileged Mode: The container runs with privileged: yes to allow access to hardware devices.
• Environment Variables:
  • KASM_PORT: Defines the listening port for the application.
• Volume Mounts:
  • /data/kasm:/opt: Mounts the main application data directory.
  • /data/kasm/profiles:/profiles: Mounts the directory for user profiles.
  • /dev/input:/dev/input: Mounts input devices for hardware passthrough.
  • /run/udev/data:/run/udev/data: Mounts udev data for device management.
• Port Mappings:
  • 3000:3000: Maps the web interface port.
  • {{ kasm_port }}:{{ kasm_port }}: Maps the dynamic application port.
• Restart Policy: unless-stopped ensures the container restarts automatically unless manually stopped.

Docker Engine Setup¶

The Docker engine is configured with the following steps: * Installation of dependencies: ca-certificates, curl, gnupg. * Installation of Docker via the docker-managed-install role. * Configuration of the Docker daemon using /etc/docker/daemon.json. * Replacement of Docker Compose version 1.42 with version 1.52 to ensure compatibility.

Proxy Servers¶

The deployment includes the configuration of SSL certificates using Let's Encrypt to secure the web interface.

• Certificate Authority: Let's Encrypt is used to issue SSL certificates.
• Installation: The letsencrypt package is installed on the host.
• Certificate Issuance: Certificates are issued using the certbot command with the following flags:
  • --standalone: Runs a temporary web server for validation.
  • --agree-tos: Agrees to the Terms of Service.
  • --register-unsafely-without-email: Registers without providing an email address.
  • --preferred-challenges http: Uses HTTP-01 challenge for validation.
  • -d <domain>: Specifies the domain name for the certificate.
• Certificate Integration:
  • Existing Kasm certificates in /opt/kasm/current/certs/ are renamed with a .bak extension.
  • The new private key (privkey.pem) is copied to /opt/kasm/current/certs/kasm_nginx.key.
  • The new full chain certificate (fullchain.pem) is copied to /opt/kasm/current/certs/kasm_nginx.crt.

Starting, Stopping, and Updating¶

The Kasm Workspaces services are managed using specific scripts located in the installation directory.

• Start Services: Execute the command /opt/kasm/bin/start to launch the application and its dependencies.
• Stop Services: Execute the command /opt/kasm/bin/stop to halt the application.
• Service Management: The Docker daemon service is managed via systemd and is configured to start automatically on boot.