What you need

The source code is open: clone the repository with git clone https://github.com/sleep3r/colloq.git. You need Docker with a running daemon, Node.js 22 or newer and npm; dependencies are installed from the lockfile with npm ci. To run a class on your own computer you don't need the source — pip install colloq is enough. The production setup on k3s is described separately.

The development .env is created by the first command that needs it: make dev, make up, make run, make host or make env-use. It is the same file colloq start writes: kernels in Docker, a random kernel token of its own, BIND_ADDR=127.0.0.1. .env.example is the full reference of settings and the template for a server installation (it has KERNEL_BACKEND=broker); you don't need to copy it to .env for development. make dev always listens on 127.0.0.1 only. For make up and make run, BIND_ADDR sets the address: without that line the port is open on every interface, Wi-Fi included.

A class without the source

pip install colloq
colloq start

The teacher package contains the built app; you need Node.js 22 or newer and Docker — each room gets its own container with Python. colloq start runs the class in this terminal and opens the browser; Ctrl+C saves and stops it. colloq host <name> gives you a link for the classroom, colloq doctor checks everything before class, and colloq backup backs up the database and files; colloq --help shows the rest. State is kept in ~/.colloq (set COLLOQ_HOME to use another directory) and survives reinstalling the package. The package interface is in English by default; to change it, see the language guide.

Quick start in Docker

make up

The command creates a local configuration, builds the kernel image and starts the app. Each room gets its own container; there is no shared instance-wide Jupyter. Open the app at http://localhost:3000 and finish the owner setup.

Data and files live in the local data/ and workspace/ directories. The development backend has access to the Docker socket; use it for trusted local development, not as a production security boundary.

The app on the host

npm ci
make dev

make dev builds the room kernel image if needed, runs the server with reload and Vite in this terminal, and opens http://localhost:5173/admin; OPEN=0 skips the browser. The server listens on PORT from .env (3000 by default) on 127.0.0.1 only. A server reload doesn't touch room kernels; Ctrl+C stops everything, including the kernels of this database. macOS needs no special permission: COLLOQ_UNSAFE_DEV_FILES no longer changes anything. To build the host server and run it in the background, use make run.

If an older clone's .env still has KERNEL_BACKEND=broker (make up used to copy .env.example), make dev refuses and names the fix: change it to KERNEL_BACKEND=docker, or move .env aside so it is written again.

Development environments

make env-list
make env-new NAME=nlp
# Edit the requirements in kernel/environments/
make env-build NAME=nlp
make env-use NAME=nlp

These are Docker development commands. In production, environments are published in advance and chosen from the digest catalog, as described in the environments guide.

Interface text

Paired translations live in shared/locales/: admin.ts, room.ts, server.ts, activity.ts and common.ts. Add the Russian and English text under one key, and call tr(key, params) from shared/i18n.ts where the text is shown. Pass names and other variables as parameters; use plural forms for counts and the shared formatting functions for dates and numbers.

In Svelte, a translation must be computed reactively when it is shown: a translation stored in a constant when the module loads won't update. Native editor elements can subscribe to language changes, so you don't need to recreate the whole editor for a label. Protocol values, file names and text written by users don't go through the translator. tests/i18n.test.mts checks that both languages are present and that parameters match; the instance-language, admin-language and language-room tests cover how the switcher behaves.

Checking changes

npm run typecheck
npm test
npm run build

Also run the integration scenarios from tests/README.md that relate to your change. A green local test run doesn't replace a deployment smoke test, network checks, backup and restore, and a real GPU operation on the target VM.

These docs are built from docs/pages/ru and docs/pages/en by python3 docs/build.py; the generated HTML is never edited by hand. Commit the rebuilt site/docs together with the sources: the “Docs up to date” CI check rebuilds it and fails if they differ. When you delete a page, also delete (git rm) its site/docs/<slug>.html.

If a kernel doesn't start, check the Docker daemon, that the image exists, socket permissions and workspace paths. Don't plug in one shared Jupyter endpoint as a temporary stand-in for separate rooms.