Guideng

Guideng is a self-hosted family location sharing app. It has a Rust server in server/ and a React + Vite + TypeScript web client in client/.

Features

• One server URL and one shared token for login.
• Built-in privacy rules and license agreement on the login page; users must accept them before login.
• Mobile browser location sharing through the Geolocation API.
• Custom device names.
• Chinese and English UI.
• Chinese/English admin console for viewing devices, deleting devices, clearing location records, and configuring automatic cleanup for inactive devices.
• AMap support.
• Automatic coordinate conversion for China map providers: AMap uses GCJ-02, while the database keeps raw GPS coordinates.
• MySQL 8 storage with a connection pool and one week of location history per device.
• Docker, Docker Compose, and Zeabur deployment templates.

Quick Start

docker compose up -d

Then open http://localhost:3000.

Default server URL in local Docker is http://localhost:8080.

If no token is provided, the server generates a 128-character random token on startup and writes it to the log. You can also set a fixed token manually:

GUIDENG_TOKEN=replace-with-a-long-random-token docker compose up -d

Development

Server:

cd server
GUIDENG_TOKEN=dev-token \
GUIDENG_DATABASE_URL='mysql://guideng:guideng@127.0.0.1:3306/guideng' \
cargo run

Client:

cd client
npm install
npm run dev

Client Assets

The app logo is stored at client/public/assets/guideng-logo.png. In the client, reference it as /assets/guideng-logo.png; Android/iOS wrappers can reuse the same asset.

Build Docker Images

./build-and-push.sh
TAG=v0.1.0 ./build-and-push.sh
PUSH=0 PLATFORM=linux/amd64 ./build-and-push.sh
IMAGES=server ./build-and-push.sh
IMAGES=client VITE_DEFAULT_SERVER_URL=https://guideng.example.com ./build-and-push.sh

The script builds guideng-server and guideng-client images. It automatically prefers Depot when available and falls back to Docker Buildx.

Server Environment

• GUIDENG_TOKEN: shared API token. When unset or empty, the server generates a 128-character random token and writes it to the log.
• GUIDENG_ADMIN_PASSWORD: admin console password. When unset or empty, the server generates one and writes it to the log.
• GUIDENG_ADMIN_PATH: admin console path, default /admin. For deployment, use a hard-to-guess path such as /admin-your-random-path.
• GUIDENG_BIND: bind address, default 0.0.0.0:8080.
• GUIDENG_DATABASE_URL: MySQL connection URL, default mysql://guideng:guideng@mysql:3306/guideng. URL-encode special characters in passwords.
• GUIDENG_LOG_PATH: log file path. By default it writes to server/guideng.log; Docker Compose sets it to /data/guideng.log.
• GUIDENG_CORS_ORIGINS: comma-separated allowed origins, default *.
• GUIDENG_AMAP_WEB_JS_API_KEY: AMap Web JavaScript API key.
• GUIDENG_AMAP_WEB_JS_SECURITY_CODE: AMap Web JavaScript API security code.
• GUIDENG_AMAP_ANDROID_KEY: AMap Android SDK key for future Android app builds.
• GUIDENG_AMAP_IOS_KEY: AMap iOS SDK key for future iOS app builds.

API

All /api/* endpoints require one of:

• Authorization: Bearer <token>
• X-Guideng-Token: <token>

Endpoints:

• GET /health
• GET /api/config: get map provider and AMap key configuration.
• GET /api/devices
• POST /api/devices
• PATCH /api/devices/:id
• POST /api/devices/:id/location
• GET /api/devices/:id/tracks?days=7

The server stores every location report and keeps the most recent 7 days of history. Older points are pruned when new locations are written.

Admin Console

The server includes an admin console. The default path is:

http://localhost:8080/admin

If you set GUIDENG_ADMIN_PATH, open that path instead. The admin password comes from GUIDENG_ADMIN_PASSWORD; if it is not set, the server generates one on startup and writes it to the log.

The admin console supports Chinese and English. Use the English / 中文 button in the upper right, or append ?lang=zh or ?lang=en to the URL.

The admin console can:

• View registered devices and their latest locations.
• Delete location records for a device.
• Delete a device.
• Manually delete devices that have not updated for a specified number of days.
• Configure automatic cleanup by day count; save an empty value to disable automatic cleanup.

Notes

Mobile browsers usually require HTTPS for high-accuracy geolocation outside localhost. When deploying, put both client and server behind HTTPS.

For detailed local deployment, see Local Deployment Guide / 中文部署指南.

Local Nginx Reverse Proxy

The root nginx.conf is intended for running Docker Compose locally first, then using host Nginx to reverse proxy the server port.

docker compose up -d
sudo cp nginx.conf /etc/nginx/nginx.conf
sudo nginx -t
sudo systemctl reload nginx

It proxies /health, /api/, and the GUIDENG_ADMIN_PATH admin path, such as /admin or your custom random path, to 127.0.0.1:8080.

Data Storage

Docker Compose runs MySQL 8 and persists it in the guideng-mysql volume. When the volume is first created, the official MySQL image automatically runs server/init.sql to create the required tables. The script uses CREATE TABLE IF NOT EXISTS and does not overwrite existing tables or data. Use mysqldump for backups.

License

MIT