1. Sign in as a teacher
Open the personal sign-in link you got from the server owner. It looks like https://your-server/admin/k/… and opens the teacher panel. No password or email confirmation is needed.
If you are setting up your own server for the first time, open the /admin/t/… link: until the server has an owner, it prints this link to the log on every start. You can also open /admin and paste the setup token by hand. The token is stored in DATA_DIR/setup-token: /var/lib/colloq/data/setup-token in a standard k3s install, ~/.colloq/data/setup-token after pip install colloq. Enter your name and email and click “Claim this instance”. The same token lets you recover access later.
Button names in this guide are given for the English interface. The owner can choose English or Russian for the whole server.
2. Create a class
In the panel, open Classes and click “New class”. Give the class a title, then choose a Python environment, a starting notebook (“Blank”, “From a file” or “From GitHub”, public repositories only) and a format. The environment then shows in the class's row in the Classes list, and it can be changed in the class's Settings while the class's kernel is not running; see A class's environment. Under “Resources” you can set the memory and the number of processor cores for the room's kernel. You can also raise the memory during class from “Settings” in the class menu; the kernel does not restart, whether rooms run in Docker or on k3s. See Memory and CPU for a class.
| Format | Starting rules | When to choose it |
|---|---|---|
| Standard | The group edits the shared notebook and runs code. | Practice and working through problems together. |
| Lecture | Editing, running code, notebook structure and files stay with the teacher, who opens individual cells to the group. | Explaining with a live demo. |
| Council | Lecture rules; opening a cell gives everyone their own sheet. | A task followed by a discussion of the answers. |
These are starting sets of rules, and you can change them during class. Oracle access (“As set for the instance”, “Off”, “Hints only” or “Full answers”) is chosen when you create the class, within the limits of the server's mode; it cannot be changed afterwards.
3. Prepare the workspace
- Add code and notes to the notebook; upload a notebook and data if you need them.
- Run the setup cells. Make sure the libraries you need are available in the chosen environment.
- Check what students are allowed to do: editing, running code, files, the oracle and the shared screen.
- Open the class link in a separate private window and join as a student. Check this exact view before class starts.
For a lecture, upload the PDF in advance and check the projector and console. For a Council, run the shared setup code before you open the task.
4. Invite your group
Copy the class link from the panel and post it in your group chat. Students just open it in a browser and enter a name. There is no need to install Python on students' computers: code runs on the server.
If the link contains localhost, fix the server's public address first. On your own computer, colloq start --share gives the class a public address and prints the link to send (one link). Check that the link opens from another network, not only from your own laptop.
5. End the class
In the room, click the lock button, “What you can do in this room”, then End class; in the panel, the same action is End the class in the class menu. Students can still reread the materials, files, terminal history and oracle answers, but only the teacher can act. Resume class in the room, or Reopen the class in the panel, brings the original rules back.
If the room is in a course, Colloq then offers to choose materials for the class page: notebooks with their results, slides and data at one permanent link. Ending a class, publishing it and deleting the room are three different actions.
Access for other teachers
The owner adds teachers under Who can teach: click “Add a teacher”, enter a name and email, and confirm with “Add teacher”. The name and email only identify the person; Colloq sends no email. Hand the new sign-in link to the teacher privately. If a link is lost or has leaked, click “Rotate sign-in link” in that teacher's row: the old link and every session opened with it stop working.
Owners and teachers
The panel has two roles. An owner sees and changes everything: every course, every room, the staff list and the server settings. A teacher sees only what they teach: their own courses and rooms. That is how courses from different departments share one server: nobody browses other people's classes or ends up running someone else's room.
| Owner | Teacher | |
|---|---|---|
| Courses and Classes | Everything. A Mine / All switch: Mine by default, which is what they teach themselves; All shows their colleagues' courses and rooms. | The courses that list them as teaching, the rooms of those courses, and the rooms they host. |
| Host in a room | In any room. | Only in the rooms they can see in the panel. |
| Add a teacher | To any course or room; on the Who can teach screen, the Courses column. | To their own course or room, including an invitation by email. |
| Delete a course or room | Yes. | No. |
| Oracle, Environments, Resources | View and change. | View. Resources lists only their own rooms; the memory and CPU totals cover the whole server. |
Panel links to someone else's courses and rooms answer “not found”, as if they did not exist. The public /c/… and /p/… pages do not change: anyone with the link can still read them.
On the first start of the new version, everyone already on the staff list becomes a teacher of every existing course and of every room outside a course, so everyone sees exactly what they saw before. From then on an owner removes people from courses they do not teach, and new teachers start with an empty list: someone adds them to a course, or they create their own.
Course teachers
Whoever creates a course teaches it from the start. Under the course title is the Teaching strip with names; “you” marks yourself. “+ Add a teacher” searches the staff list by name or email. If the person is not there, “Invite by email” creates them and adds them to the course at once: the sign-in link is shown once, so hand it over privately, just like a link from the owner. If the email is already on the staff list, the person is simply added to the course and no new link is made: they already have one.
A course's teachers host every room in the course: the ones they created, the ones a colleague created, and the ones an owner put into the course. Taking a room out of the course takes it away from the course's teachers, except those who host it personally. A room with no hosts of its own that sits in no other course stays with the course's teachers as its hosts — otherwise only the owners would see it. The same goes for deleting a course. Changes reach open rooms at once, with no server restart.
You can always remove yourself from a course. Only an owner can remove a course's last teacher, so that no course is left with nobody but the owners.
A class without a course
A course is optional. On the New class screen the Course block has a “No course” card: the room stands on its own, and it is seen by whoever created it and by the people they add. They are added in the class settings, as the room's hosts. Only an owner can remove the last host of a room outside a course.
A class without a course can be put into one later, right from the Classes list: such a class has Add to a course… in its row and in its menu. It lists the courses you teach (for an owner, by the Mine / All switch); the course you pick gets the class at the end of its plan, as when a class is added on the course screen, and the row moves to that course's group at once. If you teach no course, the row has no such link, and the menu offers “+ New course”. A class already in a course is not moved this way: it is moved from course to course on the course screen. An archived class is not offered the action.
If you pick a course, the room goes straight into the chosen plan row, taking its topic and day, or at the end of the course. A course room can have its own hosts too: for example, a teaching assistant who runs one class without teaching the whole course.
You opened someone else's room
A teacher who opens the link to a room they do not teach comes in as an ordinary participant: under their own name, under the room's rules, without control of the kernel, the rules, the lecture or bans. A strip at the top of the room says “This room belongs to the course “…”. You are here as a participant.” and who can run it. To become a host, ask any of them to add you to the course or to the room's hosts, or ask an owner. Once you are added, reload the page: the room opens as yours.
Entering from a class page works the same way: getting past the “Participants” and “No one” settings is only for the teachers of that room.