README.md
REQIUREMENTS
Docker CE
Build a deb/rpm package
# builder/build-package <os> <os_codename> <build_tag>
# os_codename is what "lsb_release -c" outputs, e.g. buster, focal.
#
# build_tag allows building multiple versions of deb package (rpm not supported)
# targeting a single distro release (e.g. Ubuntu Bionic). If build_tag is given,
# the package name will include build_tag as part of Debian revision. For
# example:
# * with build_tag: kasmvncserver_0.9.1~beta-1+libjpeg-turbo-latest_amd64.deb
# * without build_tag: kasmvncserver_0.9.1~beta-1_amd64.deb
# You need to have .build and .deb.build for the build_tag.
#
# Packages will be placed under builder/build/
builder/build-package ubuntu bionic
builder/build-package ubuntu focal
builder/build-package debian buster
builder/build-package debian bullseye
builder/build-package kali kali-rolling
builder/build-package centos core # CentOS 7
builder/build-package fedora thirtythree
Build and test a package
builder/build-and-test-deb ubuntu focal
builder/build-and-test-rpm centos core
Open browser and point to https://localhost:443/ or https://<ip-address>:443/
3 default users are created:
- 'foo' with default password 'foobar'. It can use mouse and keyboard.
- 'foo-ro' with default password 'foobar'. It can only view.
- 'foo-owner' with default password 'foobar'. It can manage other users.
Test a package
If you want to test deb/rpm package you've already built, please use this:
builder/test-deb ubuntu focal
It will install the package inside a new container and run KasmVNC.
Open browser and point to https://localhost:443/ or https://<ip-address>:443/
Package development
deb/rpm package building and testing
First, a tarball is built, and then its files are copied to deb/rpm package as it is being built. Package testing stage installs the deb/rpm package in a fresh docker container and runs KasmVNC.
builder/build-tarball debian buster
builder/build-deb debian buster
builder/test-deb debian buster
Use build-and-test-deb to perform the whole dev lifecycle, but to iterate
quickly, you'll need to skip building the tarball (which takes a long time), and
just build your deb/rpm with build-deb and test with test-deb.
build-rpm and test-rpm are also available.
Ensuring packages have all dependencies they need.
If you're working on a deb/rpm package, testing that it has all the necessary dependencies is done via testing in a barebones environment (read: no XFCE). In this way we can be sure that runtime dependencies aren't met accidentally by packages installed with XFCE.
builder/test-deb-barebones ubuntu focal
Preparing a release
Deb and rpm packages need their versions bumped to the new release version. It can be done with:
builder/bump-package-version 0.9.4-beta
This will update corresponding package files, use git diff to see changes.
If you've ran the command and curious about Debian version specifics, here's an
explanation:
Deb version will be 0.9.4~beta-1. ~ (and not -) is required by packaging
guidelines, and -1 is Debian package revision for 0.9.4 upstream release. If
a Debian-specific patch was later added on top of 0.9.4, it'd be -2 for the
next Debian version. Rpm has a corresponding revision in its .spec file.
CI development
S3 upload code is extracted to various files in .ci. It's possible to iterate
locally by doing stuff like this:
bash -c '
. .ci/upload.sh;
prepare_upload_filename "bionic/kasmvncserver_0.9.1~beta-1+libjpeg-turbo-latest_amd64.deb";
echo $upload_filename;'
vncserver development
Building a Ubuntu Focal package
builder/build-package ubuntu focal
You don't need to build-package every time you change something, but you need
Xvnc and other files.
Running a development environment
builder/devenv-vncserver
devenv-vncserver starts a dockerized development environment. Edit
vncserver, its modules, and configuration files as usual. When you
runvncserver, not /usr/bin/vncserver will be used, but ./unix/vncserver.
Same for configuration files.
Python specs can be run with ty alias inside devenv.
Debug output
To see vncserver output, run ty -d. Anything you print inside vncserver
with say should be visible that way.
Finding which spec produces a warning
By default, each passing test is represented as a dot. -v flag causes tests to
emit test descriptions alongside the program's output. Run ty -v.
ARM
KasmVNC is supported on ARM, however, the build process needs to be broken into two parts with one occuring on a x64 system and the other on an ARM system. All our testing and official builds are done on AWS Graviton instances.
Build www code on x86 System
The www code is webpacked for performance and thus requires building. There are NPM packages, phantomjs, which do not have an ARM build. Therefore, this must be built on x86 and then copied over to the ARM system for final packaging.
cd ~/KasmVNC
mkdir builder/www
sudo docker build -t kasmweb/www -f builder/dockerfile.www.build .
sudo docker run --rm -v $PWD/builder/www:/build kasmweb/www:latest
cd builder
tar -zcvf /tmp/kasm_www.tar.gz www
Now transfer kasm_www.tar.gz to the ARM system.
Build KasmVNC ARM
These instructions assume KasmVNC has been cloned at $HOME and kasm_www.tar.gz has been placed at $HOME as well, adjust for your environment.
cd ~
tar -zxf kasm_www.tar.gz -C KasmVNC/builder/
cd KasmVNC
sudo builder/build-package ubuntu bionic
The resulting deb package can be found under ~/KasmVNC/builder/build/bionic
Replace bionic with focal to build for Ubuntu 20.04LTS. At this time, only Ubuntu Bionic has been tested, however, other Debian based builds we support should also work.