FindMy WebApp - A Multi-User Find My Alternative

A self-hosted, multi-user web application designed as an alternative to Apple's Find My service. It tracks Apple devices (e.g., AirTags, iPhones, MacBooks) using FindMy.py and features a modern Material 3 interface.

Interactive Map View	Device Management Dashboard

---

Overview

This project provides a self-hosted web interface to locate Apple devices. It periodically fetches location data using FindMy.py and displays it on an interactive map powered by OpenStreetMap and Leaflet.js.

Key Features

• Multi-User Support: Each user manages their own Apple credentials and devices.
• Apple Device Tracking: Supports .plist or .keys files (e.g., OpenHaystack) for device association.
• Interactive Map: Displays device locations with dynamic icons, popups, and history trails.
• Geofencing: Create zones and receive entry/exit notifications.
• Push Notifications: Alerts for geofence events, low battery, and more.
• Device Sharing: Generate secure, time-limited revocable public links for live location sharing.
• Material 3 Design: Responsive UI with light/dark modes and dynamic theming.
• PWA Support: Installable as a Progressive Web App with offline caching.
• Dockerized Deployment: Easy setup with Docker and Docker Compose.

---

Technology Stack

• Backend: Python 3.11+, Flask, Waitress (WSGI), APScheduler
• Device Interaction: FindMy.py
• Frontend: Vanilla JavaScript, HTML5, CSS3
• Mapping: Leaflet.js
• Styling: Material 3 Design, Material Color Utilities
• Push Notifications: pywebpush, Web Push API, VAPID
• Deployment: Docker, Docker Compose

---

Getting Started

Prerequisites

• Python: 3.11 or higher
• Docker & Docker Compose: For deployment
• Apple ID: Must have Two-Factor Authentication (2FA) enabled and previously signed into an Apple device or a virtual one (e.g., Docker-OSX).

Installation

1. Clone the repository:

   git clone https://github.com/ghd182/findmy-webapp.git && cd findmy-webapp

Local Development (Not Recommended for Full Functionality)

2. Create a virtual environment and install dependencies:

   python -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

3. Configure environment variables in a .env file (see .env.example).
4. Run the app:

   python run.py

5. Access the app at http://localhost:5000.

Docker Deployment (Recommended)

2. Configure docker-compose.yml:
   • Set environment variables (e.g., SECRET_SEED, FERNET_SEED, VAPID_SEED).
   • Adjust optional variables as needed.
3. Build and run the containers:

   docker compose up -d

4. Access the app at http://<your-docker-host-ip>:5000.

---

Usage

1. Access & Register/Login: Open the app URL. Create an account or log in.
2. Set Apple Credentials: Navigate ☰ Menu ➔ Apple Credentials. Enter your Apple ID email and your regular Apple ID password. Save. (An initial data fetch is triggered).
3. Upload Device Files: Navigate ☰ Menu ➔ Settings ➔ Manage Device Files. Upload .plist or .keys files. (Another fetch is triggered).
4. View Map: Go to Map tab. Devices appear after background fetch. Use controls (Zoom, My Location, Show All, History Toggle/Slider). Click markers for info popups.
5. View Devices: Go to Devices tab for list. Click item to center map. Use ⋮ menu (Edit, Share, Geofences, Test Notifications, Remove). Toggle map visibility (eye icon).
6. Manage Geofences: Go to Geofences tab. Create global areas ("+" button). Link/unlink devices and configure notifications per link in device cards.
7. View Alerts: Go to Alerts tab for notification history. Manage read/unread/delete.
8. Configure Settings: Go to Settings tab. Manage theme/color, map defaults, notification permissions, import/export, manage active shares, delete account.

---

Gallery

Main Features

Map View	Devices List	Navigation Menu

Device Management

Device Options	Share Creation	Shared View

---

Troubleshooting / FAQ

See details

• Login Failed / Background Fetch Errors / 2FA Required:
  • Cause: Authentication with Apple failed.
  • Solution:
    1. Ensure you entered your correct Apple ID email and REGULAR password (not an App-Specific Password).
    2. Verify 2FA is ENABLED on the Apple ID account.
    3. Confirm the Apple ID has been previously used on an Apple device (iPhone, Mac, etc.) or signed into iCloud within a macOS virtual machine (e.g., using Docker-OSX) to establish trust.
    4. Check the Anisette server status (docker compose logs anisette). If it's crashing or showing errors, the authentication process will fail. Ensure it's running and ANISETTE_SERVERS points to it.
    5. Check the findmyapp logs (docker compose logs findmyapp) for specific error messages from FindMy.py.
• No Devices Showing: Check credentials, file uploads, wait for fetch interval, trigger manual refresh (Devices ➔ Update Status), check server logs (findmyapp and anisette).
• Notifications Not Working: Check browser permission, VAPID setup (VAPID_SEED, VAPID_CLAIMS_EMAIL), subscription status (Settings), geofence link notification toggles, low battery threshold, cooldown period.
• Map Issues: Clear cache, check internet, check browser console (F12).
• Docker Permissions: Ensure host ./data directory is writable by the container user (often UID/GID 1000). Use sudo chown -R 1000:1000 ./data or Docker volumes.
• VAPID Seed Failure: If logs mention "scalar... outside the valid range", use a different random string for VAPID_SEED and restart.
• Updating: Pull latest code (git pull), rebuild images (docker compose build), redeploy (docker compose up -d or Portainer "Update the stack" with "Re-pull image").
• Data Storage: User data in data/ (mapped to /app/data in container).
• Important: If you delete the container, this data is lost unless you use Docker volumes.
• Anisette Server: If you are using the Anisette server, ensure it is running and accessible.
• Web Bluetooth Scanner: The scanner tab is experimental and has limitations. It cannot reliably identify standard Find My packets from .plist/official devices due to Web Bluetooth MAC address obfuscation. It only works for OpenHaystack devices with Haystack Service Data UUID or static .keys files.

---

Future Improvements / Roadmap

See TODO.md for a detailed list. Key areas include database migration, Play Sound/Lost Mode, performance tuning, enhanced security, and UI polishing.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Credits & Acknowledgements

This project uses the following third-party libraries and tools:

• FindMy.py (MIT License): Core library for interacting with Apple's Find My network.
• OpenHaystack (AGPL-3.0 License): Firmware and tools for custom tracking tags.
• Dadoum/anisette-v3-server: Anisette server for authentication.
• Material Color Utilities (Apache-2.0 License): Dynamic theming utilities.
• Leaflet.js (BSD-2-Clause License): Interactive map library.
• OpenStreetMap (ODbL 1.0): Map data source.

Please refer to the respective repositories for detailed license information.

---

Contributing / Contact

Contributions are welcome! For questions, feedback, or support, please open an Issue Repository or submit a Pull Request. Consider adding tests and following existing code style.

Disclaimer: This project relies on unofficial methods to interact with Apple's services. These methods may change or break without notice. Using your Apple ID credentials in third-party applications carries inherent security risks. This project is intended for personal, educational purposes and is not affiliated with or endorsed by Apple Inc. Use responsibly and at your own risk. Respect privacy laws.