# dove

**dove** (Italian for *where*) is a minimal location tracker for families and small groups: *where are we today?* One program (static binary, no dependencies, no database) that:

- receives positions from phones running the free **Traccar Client** app (or OsmAnd, or anything speaking the OsmAnd/Traccar protocol);
- receives positions from **amateur radios** through APRS (direct RF, digipeaters and igates, DMR via BrandMeister, D-STAR via DPRS), and merges them with the phone into a single track;
- shows a **web map** (OpenTopoMap / OpenStreetMap) with each person's position and track, distance and elevation gain, and **Today · Yesterday · 3 days** buttons;
- sends an **alert** the first time each day someone starts moving, with the link to the map: **Telegram**, **email**, **ntfy**, **webhook** or any **command** (for example OMEMO-encrypted XMPP).

Made for people who hike, walk or ride alone: if something happens, whoever has the link sees at once where they were and how old the last position is.

The page follows the browser language (English or Italian); add `?lang=en` or `?lang=it` to the link to force one.

License: **GPL-3.0-or-later** (see `LICENSE`). Leaflet, embedded in the binary, is BSD-2-Clause (see `leaflet/LICENSE`).

## Privacy

- The page has no login: it is protected by a **secret token in the link** (128 bits, like a sharing link). Whoever has the link sees the positions; everybody else gets a 404. If the link leaks, regenerate the token and the old link stops working.
- The token is never sent to the tile servers (`Referrer-Policy: origin`), and the page asks search engines not to index it.
- Data stays **on your server**: one text file per day, deleted after 3 days (configurable). No external service except the map tiles and the alert channel you choose.
- Only the identifiers listed in the configuration are accepted.

## Installation

You need a machine that is always on and reachable from the internet (a mini PC, a Raspberry Pi, a VPS). Static binaries for Linux x86-64, ARM64 and ARMv7 are provided; for anything else see "Building".

```
sudo install -m 755 dove-linux-amd64 /usr/local/bin/dove
sudo mkdir -p /etc/dove /var/lib/dove
sudo cp dove.conf.example /etc/dove/dove.conf
# secret token for the link (at least 16 characters)
head -c 16 /dev/urandom | base64 | tr '+/' '-_' | tr -d '=' | sudo tee /etc/dove/token
```

Edit `/etc/dove/dove.conf`: at least `link` (the public address), the `[people]` section and one alert channel. The example file is commented line by line.

Test the alert channels:

```
sudo dove -c /etc/dove/dove.conf -test
```

Run it with systemd, as a dedicated unprivileged user:

```
sudo useradd -r -s /usr/sbin/nologin -d /var/lib/dove dove
sudo chown -R dove: /var/lib/dove
sudo chown root:dove /etc/dove/token /etc/dove/dove.conf
sudo chmod 640 /etc/dove/token /etc/dove/dove.conf
```

`/etc/systemd/system/dove.service`:

```
[Unit]
Description=dove location tracker
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/dove -c /etc/dove/dove.conf
User=dove
Restart=always
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/var/lib/dove
PrivateTmp=yes

[Install]
WantedBy=multi-user.target
```

```
sudo systemctl enable --now dove
```

Without systemd, one line in `/etc/rc.local` is enough:

```
(/usr/local/bin/dove -c /etc/dove/dove.conf >>/var/log/dove.log 2>&1 &)
```

## Exposing it to the internet

dove listens on two ports:

- **5055** (`in`): the phones send positions here. Open/forward it on your router.
- **8083** (`web`): the page. Keep it on `127.0.0.1` and put an HTTPS reverse proxy in front of it.

**Caddy** (automatic Let's Encrypt certificate):

```
dove.example.org {
    reverse_proxy 127.0.0.1:8083
}
```

**nginx**:

```
server {
    listen 443 ssl;
    server_name dove.example.org;
    ssl_certificate     /etc/letsencrypt/live/dove.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dove.example.org/privkey.pem;
    location / { proxy_pass http://127.0.0.1:8083; }
}
```

The link to give to your family is `https://dove.example.org/<token>/` (it is also in every alert).

## On the phone: Traccar Client

1. Install **Traccar Client** (Android: Play Store or F-Droid; iPhone: App Store).
2. **Device identifier**: the id written in `[people]` (for example `mario`).
3. **Server URL**: `http://dove.example.org:5055` (or your public IP).
4. Accuracy **high**, interval 60 seconds (or less during outings).
5. Allow location "all the time" and exclude the app from battery optimisation, otherwise Android will stop it.
6. Start the service when you head out.

Positions with accuracy worse than 200 m (`max-acc`) are dropped, and so are 0,0 positions (GPS without a fix).

## Phone and radio (APRS)

A phone needs mobile data. In the mountains that is often missing exactly where it matters. If you are a licensed radio amateur, dove can also follow you by radio.

**What APRS is.** The Automatic Packet Reporting System is a radio amateur network: a radio with GPS sends a short position packet ("beacon") every few minutes, usually on 144.800 MHz in Europe (144.390 MHz in North America). Stations called *digipeaters* repeat it, and *igates* forward it to the internet, to a worldwide network called **APRS-IS** (the data you see on [aprs.fi](https://aprs.fi)). Digital voice networks feed APRS-IS too: **DMR** radios with GPS through BrandMeister, **D-STAR** radios through DPRS.

dove connects to APRS-IS **read-only** (it never transmits), follows the callsigns you list, and adds their positions to the right person:

```
[aprs]
mario = IZ0ABC-7, IZ0ABC-9
```

Radio points appear on the map as small antennas; if the last position came by radio, the page says so (it usually means the phone has no signal).

The two paths are **independent and complementary**:

| | Phone | Radio (APRS) |
|---|---|---|
| Needs | mobile data | an igate/digipeater (or a DMR/D-STAR repeater) within radio range |
| Licence | no | **yes**: transmitting requires an amateur radio licence and a callsign |
| Points | every minute or so, a few metres | every few minutes, about 18 m (more with the DAO extension) |
| Privacy | stays on your server | **public**: anyone can see APRS positions on aprs.fi |

Either one alone is enough: without a licence or a radio, dove works with the phone only. The only part they share is the dove server itself, which must be online.

Things to know:

- The radio must have a **GPS fix**: beacons without one carry position 0,0, and dove drops them.
- Coverage depends on the infrastructure: igates are common in many areas, but a deep valley may reach none.
- APRS-IS: dove logs in with your base callsign and SSID `-DV` (set `login =` to change it) and password `-1`, i.e. as a receive-only client. Server `rotate.aprs2.net:14580` by default (`server =`).
- Supported formats: uncompressed, compressed and Mic-E position reports (Kenwood, Yaesu and most handhelds), with altitude, speed and the DAO precision extension; also third-party packets.

## Alert channels

| Section | What you need |
|---|---|
| `[telegram]` | a bot created with @BotFather (the official one, blue check mark) and the group `chat_id` |
| `[email]` | an SMTP server (port 587 or 465), user and password; for Gmail an "app password" |
| `[ntfy]` | the URL of an ntfy topic (ntfy app on Android/iOS) |
| `[webhook]` | a URL that accepts a JSON POST |
| `[command]` | a program that reads the text on stdin |

Several channels can be enabled together (they fire in parallel; on error they retry after 30 s and 2 min), including several of the same type (`[email.2]`). WhatsApp has no free official API for sending messages; unofficial services such as CallMeBot can be plugged in through `[webhook]` or `[command]`.

### Encrypted XMPP (OMEMO), optional

`omemo-sendxmpp` is a small Python script that sends an OMEMO-encrypted message to an XMPP group chat or contact. Only needed if you use XMPP; it requires `python3-slixmpp-omemo` and `python3-xmlschema` (Debian/Devuan packages). Account configuration in go-sendxmpp format (`username:`, `password:`, `jserver:`, `port:`), then:

```
[command]
run = /usr/local/bin/omemo-sendxmpp -f /etc/dove/xmpp.conf -c -a dove room@conference.example.org
```

Use a dedicated account for the bot: once an account publishes OMEMO keys, clients will also encrypt the replies sent to it.

## Building

Go 1.22 or newer:

```
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dove .
```

For a Raspberry Pi: `GOOS=linux GOARCH=arm64` (or `GOARCH=arm GOARM=7` for 32-bit models).

## Files

| File | Contents |
|---|---|
| `/etc/dove/dove.conf` | configuration |
| `/etc/dove/token` | secret token of the link |
| `/var/lib/dove/YYYY-MM-DD.jsonl` | points of the day (all people, phone and radio) |
| `/var/lib/dove/last-<id>.json` | last known position of each person |
| `/var/lib/dove/alert-<id>.last` | day of the last alert sent |

## Protocol

Positions are accepted on the `in` port as an HTTP GET or POST in the OsmAnd format (`?id=mario&lat=45.1&lon=9.2&timestamp=...&speed=<knots>&accuracy=<m>&altitude=<m>`) or as the JSON body sent by Traccar Client 9+. The answer is always `200 OK`, even for dropped points, so apps do not retry forever.
