Set up a Kehai server

For the person in the family who runs things.

Kehai has no central server. Your family signs in to one that you run, and their locations stay on it. This page takes you from nothing to a server they can sign in to.

What you need
With Docker
From a release
From source
HTTPS
Invite your family

What you need

A computer that stays on. A home server, a NAS that runs Docker, or a small rented server. Linux or macOS.
An address the phones can reach from anywhere. A domain name pointed at the computer, or a name on a private network such as Tailscale that every phone has joined.
A contact for the map services. The server asks OpenStreetMap's services for map data and sends your email or a web address with each request, so they can reach you if it misbehaves. It won't start without one.

Pick one of the three ways below. Docker is the quickest. A release is one download with nothing else to install. Building from source gets you the newest code. Change each highlighted value to your own.

With Docker

This runs Kehai with PostgreSQL. You need Docker with Compose.

1. Get the two files

mkdir kehai && cd kehai
curl -LO https://raw.githubusercontent.com/grmrgecko/kehai/main/compose.yaml
curl -L -o .env https://raw.githubusercontent.com/grmrgecko/kehai/main/.env.example

2. Set three values in .env

KEHAI_SERVER_BASE_URL=https://kehai.example.org
KEHAI_MAP_CONTACT=[email protected]
POSTGRES_PASSWORD=a long random password

The first is the address your family will type. The second is the contact for the map services. The third is the database's password, letters and digits only; openssl rand -hex 24 makes one.

3. Start it and create your account

docker compose up -d
docker compose exec kehai kehai user create you 'a long password' \
  --admin --display-name 'Your Name'

The server now answers on port 8090. Everything it keeps is in the data folder beside the two files: the database, and the config with the server's keys. Back up that folder as one.

To upgrade, run docker compose pull and then docker compose up -d.

From a release

Each release has the server already built for Linux and macOS, as one file with its web pages inside. It uses SQLite for its database. You need nothing else installed.

1. Download and unpack

Set linux-amd64 to your system: linux-amd64 or linux-arm64, or darwin-arm64 or darwin-amd64 for a Mac.

system=linux-amd64
latest=$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/grmrgecko/kehai/releases/latest)
version=${latest##*/v}
curl -fLO "https://github.com/grmrgecko/kehai/releases/download/v$version/kehai-$version.$system.tar.gz"
tar -xzf "kehai-$version.$system.tar.gz"
cd "kehai-$version.$system"

You can also pick the file by hand on the latest release page, where checksums.txt lists every file's SHA-256.

2. Install

sudo ./install.sh

It asks for the address your family will reach the server at and the contact for the map services, then installs the server as the next section's table shows, and registers it with systemd. On a Mac, run ./install.sh without sudo.

3. Start it and create your account

sudo /usr/local/bin/kehai service start
sudo -u kehai /usr/local/bin/kehai user create you 'a long password' \
  --admin --display-name 'Your Name'

To upgrade, download the new release and run sudo ./install.sh in it, then sudo /usr/local/bin/kehai service restart. Your config and data are kept.

From source

This builds the server on the machine and installs it as a service, with SQLite for its database. You need Git, Go 1.27, Node.js, and make.

1. Get the source and build

git clone https://github.com/grmrgecko/kehai.git
cd kehai
make

make builds the server for the machine you are on, with its web pages inside it, into the build folder. It installs nothing.

2. Install

sudo make install

It asks two questions: the address your family will reach the server at, such as https://kehai.example.org, and the contact for the map services. Then it puts everything in the usual places:

What	Where
The server	`/usr/local/bin/kehai`
The config, with keys made for this server	`/etc/kehai/config.yaml`
The database and everything else it keeps	`/var/lib/kehai`

The server runs as its own kehai account, which the install makes, and is registered with systemd.

To answer the questions ahead of time, in a script for example, give both on the command line:

sudo KEHAI_SERVER_BASE_URL=https://kehai.example.org \
  KEHAI_MAP_CONTACT=[email protected] make install

3. Start it and create your account

sudo /usr/local/bin/kehai service start
sudo -u kehai /usr/local/bin/kehai user create you 'a long password' \
  --admin --display-name 'Your Name'

The server now answers on port 8090. Back up /etc/kehai and /var/lib/kehai together, since the config holds the key that unlocks part of the database.

Upgrading, and installing without root

To upgrade, run git pull, make, and sudo make install again, then sudo /usr/local/bin/kehai service restart. An install never touches a config that is already there.

Run make install without sudo and it installs for your own account, under ~/.local and ~/.config/kehai. This is the way on a Mac.

HTTPS

The apps send a password to your server, so it needs HTTPS. They warn before sending one without it. There are two ways to get it:

A reverse proxy such as nginx or Caddy, with a certificate, in front of port 8090. Pass WebSocket connections on /ws, and list the proxy's address under server.trusted_proxies in the config so the server sees your family's addresses and not the proxy's.
The server's own certificate. Set server.tls.self_signed in the config and the server makes one. Each phone shows its fingerprint once, and you confirm it matches the one in the server's log.

The configuration reference lists every setting.

Invite your family

Open the server's address in a browser and sign in with the account you made.
Create a group, then make an invite for each person from the Groups page.
Send each invite however you like. It ends on a link and a QR code.
Each person installs the Kehai app and opens their invite. The app takes it from there.

iPhones need nothing more from you. Their alerts pass, encrypted, through a relay the project runs, which the privacy policy describes. Android phones get theirs straight from your server.