kokkoja-rel/docs/host.md

# A host's Kokkoja

The host starts a session, invites the guests and drives the session:
puts images on the page, starts new pages, loads pages from a notebook,
and decides which guests may do the same.  In a lesson, the teacher is
the host.  Everything in [A guest's Kokkoja](guest.md) applies to the host
too; this part describes what is added, and how to install the Kokkoja
program, which a host needs.

## Installing the Kokkoja program

A guest can join from a web site with nothing installed.  A host runs the
Kokkoja program on their own computer.  It is a small Python program with
two jobs: it shows Kokkoja in your web browser, and it reads and writes
your notebooks as ordinary directories and files.  It listens only to
your own computer and talks to nothing else but the relay you name.

You need:

* **Linux or macOS.**  Windows has not been tried yet.
* **Python 3.**  Linux has it.  On macOS, open Terminal and type
  `python3 --version`; if Python is not installed, macOS offers to
  install the command line developer tools, which include it.  Any Python
  from 3.9 on will do.
* **A web browser.**  Firefox, Brave or Chrome; other browsers built on
  the same engines very probably work.
* **A pen tablet**, if you want to write by hand.  A mouse works for
  pointing and for rough marks.

Get Kokkoja from its repository, either by downloading it as a zip file
and unpacking it, or with git:

    git clone https://git.andykopra.com/ack/kokkoja-rel.git kokkoja

Nothing else is installed and nothing is changed on your system.  To
update later, download again or run `git pull` in that directory.  To
remove Kokkoja, delete the directory; your notebooks are elsewhere and
stay.

## Starting Kokkoja

Open a terminal in the Kokkoja directory and run

    python3 kokkoja.py --relay wss://kokkoja.andykopra.com/relay

The program prints an address beginning `http://localhost:8760/` and
opens your browser there.  Leave the terminal open: the program must run
as long as you are in a session.  Ctrl-C stops it.

The address the program prints contains a secret token.  Your browser
remembers it, so afterwards `http://localhost:8760/` alone brings Kokkoja
back; but if the browser ever says that the notebooks are locked, open
the full address the program printed.  The token is what stops any other
web page you might have open from reading your notebooks.

The relay address names the *Kokkoja server* you use.  A server does two
things: it passes the participants' messages, encrypted so that it
cannot read them, and it serves the web site that your guests join from.
The address above is Andy's server; whoever runs a server for you gives
you its address.  If you give the program no relay, it expects one on
your own computer, which is useful only for trying Kokkoja alone.

Other options, all optional:

* `--notebooks DIRECTORY` keeps the notebooks somewhere other than
  `Kokkoja` in your Documents directory.
* `--port NUMBER` uses another port than 8760, if that one is taken.
* `--no-browser` does not open a browser; open the printed address
  yourself.
* `--site ADDRESS` names the web site that invitations link to.  You
  need it only if your server's web site is not at the relay's host.

## Starting a session

On the start screen, enter your name and the notebook for this session,
and press **Start a session**.  You are on page 1, a blank sheet, and the
panel on the right shows the invitation.

### The notebook

The notebook you name is a directory under `Kokkoja` in your Documents
directory, made when it is first needed, and the start screen offers the
names of the notebooks you already have.  For teaching, a notebook per
student works well: everything a student is given, with everything they
and you wrote on it, gathers in that student's notebook, and the next
lesson with that student starts by naming it again.  Your library of
exercises can live in notebooks of its own, such as *Exercises A1*, filled
by keeping pages in a session of your own with nobody else present.

The notebook can be changed during a session, in **Current notebook** in
the panel.  The page you are on then continues in the new notebook.

### The invitation

**Invitation** in the panel shows a link.  **Copy** copies it; send it to
your guests by email, in a chat message, or however you reach them.  A
guest opens it, enters a name and is in.  A guest with the Kokkoja
program installed may paste it into their own program instead.  The link
carries the secret that protects the session, so send it only to those
who should be there; anyone with the link can join and read the page.
Each session you start has a new invitation.

An invitation is good as long as you keep the session open.  A guest can
join at any time, see everything written so far, and leave and return.

## Driving the session

Three buttons at the right of the toolbar are the host's.

**New** starts a new blank page for everyone.  Pages are numbered from 1
through the session.  The page being left is kept in every participant's
notebook, by itself, under a dated name; nobody has to remember to save.

**Image** puts an image file on the page for everyone.  Kokkoja's own
file chooser opens, beginning where your notebooks are and remembering
where you last chose from; a directory path can also be typed into it.
It shows small pictures of the image files it finds.  Choose one and it
is placed on the page: the first at the top of the sheet, each further
one 8 mm below the lowest image there, centred, at its natural size.  An
image wider than the sheet is scaled down to fit between the margins, so
a full-page A4 scan appears at about 92%; the chooser has a setting to
turn that off, in which case the sheet widens to the image instead.  PNG
and JPEG files are shared as they are unless very large; other formats,
and images over 2400 pixels on a side or 1.5 MB, are converted to JPEG
and reduced first.  A page holds up to 12 images.

For a page that begins with an image, press **New** and then **Image**.
For a series of exercises, keep pressing **Image** on the same page: the
sheet grows downward and everyone scrolls through them.  A new image does
not change anyone's zoom; it appears below, to be scrolled to.

If you chose the wrong file, a tap of the eraser on the image takes it
back, as long as nothing else has happened on the page since: no stroke,
no text, no erasure, no further image, by anyone.  After that an image
stays, because the marks made on it would make no sense without it.

**Notebook** starts a new page for everyone from a page kept in one of
your notebooks, with everything that was written on it.  A chooser shows
your notebooks on the left and small pictures of the chosen notebook's
kept pages on the right.  The loaded page is a copy: the kept page is
not changed by anything that happens next.  Each layer on it still
belongs to the participant who wrote it, so a student's answers from an
earlier lesson are still theirs, and your corrections still yours.

This is also how you return to an earlier page of the session: the page
was kept when you left it, and **Notebook** brings it back as a new page.
A lesson might go: **New**, **Image** for the exercise, work, **New**
for a point of grammar, work, **Notebook** to return to the exercise.

## Guests' rights

In the **Participants** list, each guest's name has a button **pages** in
front of it.  Pressing it lets that guest start new pages, put images on
the page and load pages from their notebook, exactly as you can; the
three buttons appear on their toolbar.  Pressing it again withdraws the
right, which otherwise lasts until the session ends.  Guests can never erase or
change anyone's writing but their own; that needs no setting.

## Hiding writing

The box in front of each participant's name shows or hides that
participant's writing on your screen only.  Hide a student's answers to
see the exercise clean, hide your own corrections to see what the
student sees, show them again; the others notice nothing.  **Export**
leaves hidden writing out of the picture it makes, which is how to make a
picture of the exercise with the corrections alone.

## Keeping and exporting

The page you are on is written continuously to `Current.svg` in the
current notebook, and copied to a dated file whenever the session moves
on.  **Keep page** makes such a copy now, named for the day and a serial
number, such as `2026_10_06_02.svg`; pressing it again before anything
has changed makes no second copy.  Use it to mark a state worth keeping
on its own, or to add a finished page to a notebook of exercises.

**Export** saves a picture of the page as you see it, as a PNG file at
200 dots per inch, in a directory and under a name you choose in
Kokkoja's file chooser.  Replacing an existing file takes a second press
of the button, so a slip does not overwrite anything.

The notebooks are ordinary directories, and a page is an ordinary SVG
file.  Open one in a browser or in Inkscape, attach it to an email, keep
it with your other documents.  Only Kokkoja can load it as a live page
again, with each person's writing still theirs.

## Ending a session

Close the browser tab, or stop the program with Ctrl-C in its terminal.
There is nothing to save: the page is already in your notebook, and in
each guest's.  Guests who are still connected can go on writing on the
page among themselves, but no new page can be started without you or a
guest you have given the right, and a guest who arrives after everyone
has left finds an empty session.  The next lesson is a new session with a
new invitation; load the pages you need from the student's notebook.

## When something goes wrong

* **The browser says the notebooks are locked.**  Open Kokkoja from the
  full address the program printed when it started, the one with the
  token.
* **"Disconnected" in the toolbar.**  Kokkoja reconnects by itself as
  soon as the relay can be reached, and sends what was written meanwhile.
  If it does not come back, check your connection; the page is safe in
  your notebook either way.
* **A guest sees "Waiting for the host's page".**  You have not started
  a page yet, or your connection is down.  The first page is started when
  you start the session, so this usually means the latter.
* **Pressure does not work.**  The last line of the panel reports what
  the browser receives from your pen.  If it says *mouse*, the browser is
  not seeing the pen as a pen; try the other browser.