Skip to content

Installing

You need Docker with Compose, a UniFi console running Talk, and a machine on the same network as the console. TalkWatch talks to the console over its LAN address, directly or through a private VPN, never through Ubiquiti's cloud. To run TalkWatch somewhere else, see Reaching a console from elsewhere.

To look round before you point it at a console, try the demo: the same image, with a capture from a real console replayed in place of yours. To run it on Railway rather than on the site's LAN, see Deploying on Railway.

1. A console account for TalkWatch

Create a user on the console that can see Talk but change nothing, and give TalkWatch that user's username and password. Use a separate user rather than your own: it's signed in all the time, and you'll want to be able to change or remove it without touching yours.

TalkWatch signs in by username, not e-mail address. It reads the call log, users, ring groups, numbers, voicemail and recordings, and listens to the console's live updates. It never writes anything to the console.

2. The console's certificate

Consoles ship a self-signed certificate, so TalkWatch pins it by fingerprint rather than turning certificate checks off. Get the fingerprint with the capture tool, then check it against the certificate your browser shows for the console before you trust it:

dotnet run --project tools/TalkWatch.Capture -- cert https://192.168.1.1

The fingerprint changes if the console's certificate is regenerated, and TalkWatch then refuses to connect until you give it the new one. That's the point: a changed certificate is exactly what a pin is for noticing.

3. Start it

cp .env.example .env    # then fill it in
docker compose up -d

.env holds passwords, so git ignores it. At a minimum, set:

  • DB_PASSWORD — any long random value; it never leaves the two containers.
  • TALK_CONSOLE_URL, TALK_USERNAME, TALK_PASSWORD and TALK_CERTIFICATE_SHA256.
  • BOOTSTRAP_ADMIN_USERNAME and BOOTSTRAP_ADMIN_PASSWORD (at least 12 characters) — the first admin account, made on the first start only. Remove the password afterwards.

The console's address, account and fingerprint can instead be given after the first start, on Configure → Console, which wins over these. Every setting is in Configuration. In production, give the passwords as files rather than environment variables: a file in /run/secrets named after the setting, such as Talk__Password, overrides the environment, and Docker secrets land there by default.

4. The first start

TalkWatch creates its database schema, the site and the first admin, then starts polling. The first poll copies the console's whole call history, a page at a time, and alerts on none of it: only calls from the last 30 minutes raise alerts, so an import doesn't wake anyone. Recordings and voicemail follow, 20 of each per poll, so a long history is copied over a few hours rather than hammering the console.

Sign in at http://<host>:8080 with the bootstrap admin. TalkWatch opens on Now. Add people under Configure → People and give each the lines they should see, or a role on a number (see Signing in and access).

The port is published for a first run on the LAN. Before anyone reaches TalkWatch from outside, put a reverse proxy with TLS in front of it: see Behind a reverse proxy.