What you need

A production installation is designed for one Linux amd64 VM with systemd and IPv4. You need root access, curl, Python 3, iptables (plus ip6tables on a host with IPv6) and the standard Linux utilities. A GPU release needs Debian or Ubuntu with apt, the gnupg package and a working NVIDIA driver installed in advance: the installer does not replace it. You do not need to install Node.js or the Docker daemon on the server: the application and the kernels run on k3s/containerd.

Set aside resources for k3s, the application and every room that runs at the same time. The number of connected students does not determine the load by itself: what matters is the code, memory, files and the number of active kernels. See resource planning.

Verify the release kit

Get the artifacts through a trusted channel. Verify the checksums, unpack the tools archive and work from its directory. The manifest records the source commit, the real digests of the application, broker and environment images, the exact k3s version and the hashes of the tools.

sha256sum -c SHA256SUMS
tar -xzf colloq-deploy.tar.gz
python3 scripts/release.py validate --release release.json
sudo scripts/cluster.sh validate --release release.json
scripts/cluster.sh render --release release.json > resources.json

A checksum detects corruption but does not prove that the sender can be trusted. The tools must match the chosen release: the installer rejects files that were changed locally or do not match.

Prepare the configuration

Create a private instance.env file. The k3s application reads only PUBLIC_URL, INSTITUTION, ADMIN_EMAIL, TZ, UI_LANGUAGE, OPEN_SEMINAR_CREATION, MAX_UPLOAD_MB, MAX_SESSION_MB, SESSION_SECRET and the oracle settings AI_PROVIDER, AI_REASONING, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL. The broker takes only RUNTIME_KERNEL_MEMORY and RUNTIME_KERNEL_MEMORY_MAX from the same file: a room's default memory and its ceiling (see room resources). The installer ignores every other line, including the KERNEL_* settings from the repository's .env.example. A minimal example for your own domain:

PUBLIC_URL=https://seminar.example.edu
INSTITUTION=Teaching Lab
ADMIN_EMAIL=teacher@example.edu
TZ=Europe/Moscow
OPEN_SEMINAR_CREATION=false
MAX_UPLOAD_MB=50
MAX_SESSION_MB=1024

Values are read as data, not as a shell script. Only the allowed list of variables reaches the application. The installer generates and mounts the runtime keys; do not paste them into cells or the browser.

Install and check

sudo scripts/cluster.sh install --release release.json \
  --env-file /path/to/instance.env
sudo scripts/cluster.sh status
sudo scripts/cluster.sh smoke

If the images are private, add --registry-config /path/to/pull-only-config.json to install. Use separate credentials that can only pull the images you need, not your main GitHub or Vast key.

The installer refuses an existing k3s installation it did not create, a mismatched k3s version and an old colloq.service. Migrate an old server as a separate step: keep the original machine, export the data with the tools that match it, and restore a compatible copy into the prepared installation.

Open the external address

The host proxy reaches the application at 127.0.0.1:30080. Set up HTTPS through Caddy or a relay. The Kubernetes, broker and Jupyter ports stay private.

Once the address is public, open /admin, finish setting up the owner and run your first class. Check the link from a student's device.

Checks before a real group

  • Create two rooms and run Python code in each; make sure their variables, files and Jupyter tokens are kept apart.
  • Check the network policy that is actually in effect, including requests from a room to the local node.
  • Restart the application and the broker, and check that connections to the kernels recover.
  • Go through a backup and restore, then an update and a rollback between the chosen releases.
  • For GPU, run a real CUDA operation; an HTTP health check is not enough.

Local tests check the code and how it handles failures, but they do not prove that a particular VM is set up correctly. The limits of the protection are described in the isolation model.