shounak6942/familytrack repository overview

⁠FamilyTrack

Your family’s live map. On your hardware. In one container.

FamilyTrack is a tiny, self-hosted location-sharing server: PIN-gated login, a live Google Map, optional hCaptcha, one-tap share links, and destination alerts. Built for a Raspberry Pi, a homelab NAS, or any Docker host.

docker pull shounak6942/familytrack:latest

That is the image docker-compose.yml runs (image: shounak6942/familytrack:latest, pull_policy: always).

⁠Why people run it

• Private by default — locations live in memory on your box. No family-tracking SaaS, no extra accounts.
• Family PIN + optional CAPTCHA — a shared PIN for the household; hCaptcha when you expose it to the internet.
• Live map — GPS updates as soon as the chip has a fix; WebSocket push with HTTP fallback.
• Share without inviting — time-boxed solo or group links, optional viewer PIN, instant revoke.
• Follow + speed + destination — lock onto someone, see their speed, drop a pin, get 1 km / 500 m / 200 m alerts.
• Phone-friendly — the dashboard is a PWA-style live map; Tasker / GPSLogger can push via an API key.
• Pi-ready — linux/amd64 and linux/arm64 images (Raspberry Pi 4 / Zero 2 W).

⁠60-second start

docker pull shounak6942/familytrack:latest

⁠Portainer

Paste docker-compose.yml as a stack. Leave out any build: block — Portainer has no Dockerfile, so a build: line fails with open Dockerfile: no such file or directory.

The stack must look like this (your secrets stay in environment:):

services:
  familytrack:
    image: shounak6942/familytrack:latest
    container_name: familytrack
    restart: unless-stopped
    ports:
      - "5050:5000"
    environment:
      SECRET_KEY: "paste-your-key"
      FAMILYTRACK_PIN: "3325"
      GMAPS_KEY: ""
      HCAPTCHA_SITEKEY: ""
      HCAPTCHA_SECRET: ""
      FAMILYTRACK_API_KEY: ""
      COOKIE_SECURE: "false"

Then deploy. Portainer will pull shounak6942/familytrack:latest.

⁠Docker Compose CLI

1. Copy docker-compose.yml and edit the environment: block — PIN, Maps key, SECRET_KEY.
2. Start the Hub image:

docker compose up -d

Generate a signing key and paste it into Compose as SECRET_KEY:

openssl rand -hex 32

Same image, without Compose:

docker pull shounak6942/familytrack:latest
docker run -d --name familytrack --restart unless-stopped \
  -p 5000:5000 \
  -e SECRET_KEY="$(openssl rand -hex 32)" \
  -e FAMILYTRACK_PIN="3325" \
  -e GMAPS_KEY="your_maps_javascript_api_key" \
  -e COOKIE_SECURE=false \
  shounak6942/familytrack:latest

⁠Configuration

Edit values only in docker-compose.yml. Compose does not read a .env file for this app.

Restrict the Maps key by HTTP referrer in Google Cloud Console (e.g. https://your.domain/*).

Put FamilyTrack behind Caddy, nginx, or Traefik for TLS, then set COOKIE_SECURE: "true" in Compose.

⁠Features

⁠Live locations

watchPosition sends every GPS fix immediately. Other members see it over /ws, or poll /api/ws_poll if a proxy strips WebSocket upgrades.

⁠Follow / speed

Tap a name or marker to follow. Tap the same name to unfollow. Speed is shown for the person you follow. After you pan, the map re-centres 5 seconds after the last touch.

⁠Share links (/share)

• Solo — your live position only.
• Group — visitors add a name and broadcast too.
• Duration: 15 min / 30 min / 1 h / 3 h / 8 h.
• Optional viewer PIN, independent of the family PIN.
• Revoke from /share at any time.

⁠Destination alerts

Drop a destination on the map. The browser computes haversine distance locally and notifies at 1 km, 500 m, and 200 m.

⁠External GPS

Send updates without a browser session:

curl -X POST https://your.host/api/update_location \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Asha","lat":51.5,"lng":-0.12,"accuracy":12,"speed":1.4}'

⁠Docker Hub

docker pull shounak6942/familytrack:latest

Image: shounak6942/familytrack:latest⁠ — this is what Compose uses.

The image runs one Gunicorn worker on purpose: locations and share links are in-memory. Do not scale replicas unless you add an external store.

Health check: GET /health → {"ok": true, "ws": true}.

⁠Production notes

• Prefer Compose on a Pi or VPS; put TLS in front; set COOKIE_SECURE: "true".
• Sessions last 7 days (sliding). Share-link viewers never inherit the family session.
• Stale members drop after 5 minutes without a fix.
• Keep real keys in your own copy of docker-compose.yml; rotate them if they leak.

⁠Build from source (optional)

git clone https://github.com/dallergy/familytrack.git
cd familytrack
docker build -t shounak6942/familytrack:latest .

Day-to-day runs should pull, not rebuild:

docker pull shounak6942/familytrack:latest
docker compose up -d

⁠Local development (no Docker)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export SECRET_KEY=$(openssl rand -hex 32)
export FAMILYTRACK_PIN=3325
export GMAPS_KEY=your_key
python app.py --host 0.0.0.0 --port 5000

⁠Security

• Maps JS key is injected only after a successful login (or on a share-view page you created).
• CAPTCHA is verified server-side when HCAPTCHA_SECRET is set.
• Login is rate-limited (10 attempts / 5 minutes / IP).
• Security headers: CSP, HSTS, frame denial, nosniff.
• API-key auth is optional and disabled when FAMILYTRACK_API_KEY is empty.

⁠Publishing to Docker Hub (maintainers)

GitHub Actions builds linux/amd64 and linux/arm64 and pushes shounak6942/familytrack⁠ on every push to v2 / main and on version tags.

Repository secrets used to log in:

1. DOCKER_USERNAME — Docker Hub account (shounak6942)
2. DOCKER_PASSWORD — Hub password or access token⁠ with Read & Write

The workflow also copies this README onto the Hub listing.

Use and modify for your household. See the GitHub repository for project history.