# Running the ZumiScribe services on a company server

For a company that wants nothing installed on people's computers. People open ZumiScribe in Chrome or Edge as usual and enter one address; the follow-along relay, the company glossary and the AssemblyAI helper then run on your server.

**What this guide covers, and what it does not (22 Oct 2026)**
- Covered: the three small services, as a container (Docker or Podman, with automatic https through Caddy) or as a plain program under systemd.
- **Not available on a server: Voz + Who.** Desert Ant Labs' licence for these models covers use on the user's own device and forbids offering them as a hosted service, so the server never runs them. People can use "Voz + Who (in this browser)" in ZumiScribe, or install them in the ZumiScribe Local app on their own Mac. See [PLAN-VOZ-WHO.md](PLAN-VOZ-WHO.md).
- **Granite needs no server.** IBM's Granite Speech (Apache 2.0) runs in each person's browser ("Granite (in this browser)", Chrome or Edge): nothing to install, and nothing leaves their computer. The server does not run it. See [PLAN-GRANITE.md](PLAN-GRANITE.md).
- **Not yet available: the speech engine on a server.** The local engine (Parakeet and Sortformer) runs on a Mac. A server version for NVIDIA GPUs is planned ([PLAN-LOCAL-APP.md](PLAN-LOCAL-APP.md), phase 8). Until then people transcribe with a cloud speech service (their own key) or with the engine on their own Mac.
- **There is no sign-in yet.** Anyone who can reach the server can use it. Run it only on a trusted network (your office network or a VPN), behind your own gateway or an address list, and never open to the internet. See "Security" below.

## What you need

| | |
|---|---|
| A host | any Linux machine (or a Mac) with Docker 24 or later, or Podman. About 100 MB of memory and no GPU. The services image is about 53 MB |
| A name | a DNS name that points at the host, for example `zumiscribe.company.example`, because the page is https and the server must be reached over https and wss |
| Ports | 443 (and 80 for the certificate) open to your users |
| Time | about 15 minutes |

## Step by step (Docker Compose)

**1. Get the files.** From the repository, the folder `experiments/zumiscribe/local-app/deploy` holds `compose.yaml`, `Caddyfile` and `.env.example`. Copy that folder to the host (or clone the repository there). The commands below are run from inside it.

**2. Make your settings file.**
```bash
cp .env.example .env
```
Open `.env` and set:
- `ZUMISCRIBE_DOMAIN` to your name, for example `zumiscribe.company.example`.
- `ZUMISCRIBE_ALLOWED_ORIGINS` to the address people open ZumiScribe at, for example `https://zumilabs.com`. Several, separated by commas. A page that is not on this list is refused.

**3. Start it.**
```bash
docker compose --profile https up -d
```
The first start builds or pulls the image (a minute) and Caddy fetches a certificate for your name. Expected: `docker compose ps` shows `zumiscribe` as `healthy` and `caddy` as `Up`.

To try it on one machine first, leave `ZUMISCRIBE_DOMAIN=localhost`: Caddy then uses its own certificate (your browser warns once).

**4. Check it from your own computer.**
```bash
curl https://zumiscribe.company.example/health
```
Expected: a line of JSON containing `"ok":true`, `"mode":"server"` and `"auth":"none"`. And:
```bash
curl https://zumiscribe.company.example/.well-known/zumiscribe
```
which lists where the relay, glossary and helper are.

**5. Connect ZumiScribe.** In ZumiScribe open Settings, **Services**, choose **A server**, type `https://zumiscribe.company.example` and press **Use these services**. It looks for the server, and only if it answers does it fill in the relay, helper and glossary addresses. Then press **Check my setup**: every line should be green (the speech engine and Ollama lines may say "check": they are not part of the server).

**6. Try following along.** Start a recording, press Share, open the link on a phone on the office network: the captions appear. No tunnel is needed inside the company.

## The glossary

The company glossary is one file, `glossary.json`, kept in the container's data volume. Terms in it are explained when someone clicks an abbreviation in a transcript (see [GLOSSARY.md](GLOSSARY.md) for the formats).
- To edit it:
```bash
docker compose cp zumiscribe:/data/glossary.json ./glossary.json   # copy it out (an example is created on first start)
# edit glossary.json, then:
docker compose cp ./glossary.json zumiscribe:/data/glossary.json
```
  The server reads the file again whenever it changes. A mistake in the file keeps the last good terms and `Check my setup` shows the error.
- Or mount your own file: in `compose.yaml` replace the `zumiscribe-data:/data` volume by `./glossary:/data` (a folder containing `glossary.json`, readable by user 65532).

## Updating, backing up, rolling back

- **Update:** put the new version tag in `.env` (`ZUMISCRIBE_IMAGE=ghcr.io/zumilabs/zumiscribe-services:0.1.1`), then `docker compose --profile https pull && docker compose --profile https up -d`. Rooms of people following along end; nothing else is lost.
- **Back up:** only the glossary matters (the volume `zumiscribe_zumiscribe-data`). The services keep no accounts, no audio and no transcripts.
- **Roll back:** put the previous tag back and run the same command.
- **Stop:** `docker compose --profile https down` (add `-v` to delete the glossary volume too).

## Without Docker

Build the program (needs Rust): from `experiments/zumiscribe/local-app` run `cargo build --release -p zumiscribe-server`, then copy `target/release/zumiscribe-server` to the host. `deploy/zumiscribe.service` is a systemd unit for it (it has not been tried on a Linux host yet). The program is configured by the same `ZUMISCRIBE_*` settings; run `zumiscribe-server --help`. You provide the https proxy yourself (nginx, Traefik, an ingress): it must pass WebSockets and add `X-Forwarded-Proto`.

## The settings

| Setting (environment variable) | Meaning | Default |
|---|---|---|
| `ZUMISCRIBE_MODE` | `server` or `local` | `server` in the container |
| `ZUMISCRIBE_HOST`, `ZUMISCRIBE_PORT` | where it listens | `0.0.0.0`, `8780` |
| `ZUMISCRIBE_ALLOWED_ORIGINS` | the web pages allowed to use it, separated by commas; `*` allows any page | `https://zumilabs.com` in `.env.example` |
| `ZUMISCRIBE_GLOSSARY_FILE` | the glossary file | `/data/glossary.json` |
| `ZUMISCRIBE_ENGINE_URL` | where a speech engine listens (`wss://...`), shown to the page; the server does not proxy it | none |
| `ZUMISCRIBE_DATA_DIR` | the data folder (local mode) | the Mac's Application Support folder |

## Security

- **No sign-in yet.** Every route answers anyone who can reach the server, except that a web page must be one of the allowed origins. That check protects against other web pages, not against other people on the network. Until sign-in exists (per-person tokens, then single sign-on through your own gateway, when a company asks for it), keep the server on an internal address or a VPN, or put it behind your gateway.
- **At startup** it prints a warning when it listens on a non-local address with no sign-in, and `/health` says `"auth": "none"` (Settings shows it beside the address).
- **What it holds.** No audio and no transcript text. The follow-along relay keeps captions in memory for the rooms that are open (up to 24 hours, then dropped). The AssemblyAI helper passes a key to AssemblyAI in the request being made and does not store or log it. The log shows only addresses and results.
- **The container** runs as a non-root user with a read-only root filesystem, no capabilities and no shell. The compose file also publishes the port on `127.0.0.1` only; the proxy is what the network reaches.
- **Phones need nothing installed.** The follow-along page they open is served by the relay.

## When something does not work

Open **Check my setup** (Settings, Services) in ZumiScribe. Each line says what is wrong and what to do. The usual causes:

| What you see | Cause and fix |
|---|---|
| "Nothing answered at ..." | The name does not reach the host, ports 80 and 443 are closed, or the container is not running: `docker compose ps`, `docker compose logs`. |
| "It does not allow this page to read its answer" | The page you opened ZumiScribe at is not in `ZUMISCRIBE_ALLOWED_ORIGINS`. Add it (no trailing slash), then `docker compose up -d`. |
| "This page is https but ... is not" | The server address starts with `http://`. Use the https name that Caddy serves. |
| Phones cannot open the link | The phone is not on the office network, or the Wi-Fi blocks devices from reaching each other (client isolation). |
| The certificate is not trusted | `localhost` uses Caddy's own certificate. For a real name check that DNS points at the host and ports 80 and 443 are open; read `docker compose logs caddy`. |
| Following along ends after a restart | Rooms are kept in memory only. The presenter reconnects by pressing Share again. |

## Apple's `container` tool, Podman and others

The image is an ordinary OCI image, so any OCI runtime can run it, including Podman and [Apple's `container`](https://github.com/apple/container) on a Mac. Nothing special is provided for them. The speech engine cannot use a Mac's GPU from inside any of these, which is why on a Mac it is run by the ZumiScribe app instead.
