Quick start

Run the family location tracker with Docker.

This is the README quick start, on-domain. You need Docker and Docker Compose. Go and Flutter are only required if you run the API or mobile app outside Docker.

This is enough for a laptop. Before you invite a family onto a VPS or NAS reachable from the internet, follow the production guide.

1. Start the stack

Clone wheresfrank/openfamily, copy the example env, set a strong POSTGRES_PASSWORD and JWT_SECRET, then compose up.

openfamily / setup
$ git clone https://github.com/wheresfrank/openfamily.git openfamily
$ cd openfamily
$ cp .env.example .env
# Set a strong POSTGRES_PASSWORD and JWT_SECRET
$ docker compose up -d --build

Existing deployments should retain their current DATABASE_URL, POSTGRES_USER, and POSTGRES_DB values during an upgrade. The OpenFamily database defaults are for fresh installations and do not rename stored data.

The API is at http://localhost (via Caddy):

curl http://localhost/healthz
# {"status":"ok"}

2. Create an account

curl -X POST http://localhost/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","password":"supersecret1","name":"Alice"}'

curl -X POST http://localhost/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","password":"supersecret1"}'

For a managed server (invite-only registration and the admin panel), set PLATFORM_ADMIN_EMAIL and PLATFORM_ADMIN_PASSWORD in .env before the first start.

3. Point the app at your server

  1. 1

    Install the Android APK

    Download it from the admin panel's APK / Builds page, or from the latest GitHub Release. A release APK does not need a dart-define.

  2. 2

    Enter your server URL

    On first launch the generic app asks for the origin (for example https://openfamily.example.com or your LAN IP) and stores it on the device.

  3. 3

    Create or join a family

    Use an invite code if the operator closed registration. Allow Always location and notifications. On Android, grant the battery exemption and install ntfy so SOS and geofence alerts arrive when the app is closed.

What you just ran

One Docker Compose stack: Caddy (TLS edge), the Go API (REST + WebSocket), PostgreSQL with PostGIS and TimescaleDB, and ntfy for Android UnifiedPush. That is the self-hosted Life360-style family map — not a calendar, and not a fleet tracker.

Docker ComposeGoFlutterPostgreSQLPostGISTimescaleDBCaddyntfy
Production guide Full README quick start