The Open Wearables admin seed runs once and never updates

The admin seed runs only while the developer table is empty

An admin account is created on startup from two environment variables, `ADMIN_EMAIL` and `ADMIN_PASSWORD`, and the documentation gives the defaults: `[email protected]` and `your-secure-password`. The condition on that seed is what matters. It runs only while the developer table is empty, so once any developer account exists it is skipped, and changing `ADMIN_PASSWORD` afterwards does not update an existing account.

The sequence is therefore fixed: the first start creates the default account, and every later edit of the variable is inert. The documentation does not soften this, telling you to change the default password from the developer portal right after your first login, with further accounts invited from that portal rather than created by editing configuration. The portal is served at `http://localhost:3000`, while the API documentation, an interactive Swagger UI, is at `http://localhost:8000/docs`. Both are plain http on localhost, which is acceptable on a laptop and is the reason to read the deployment documentation before exposing either to a network.

The production tag in the docs sits three releases behind the newest

`docker compose up -d` is offered as the easy way in, and then immediately qualified: it builds from local source and is meant for development. For production the documentation points at two published images, `themomentum/open-wearables-backend` and `themomentum/open-wearables-frontend`, pinned to a stable release tag rather than `nightly` or a build of `main`.

The tag given as the example is `0.7.0`. The history has moved past it: 0.7.0 on 2026-08-12, then 0.8.0 on 2026-09-11 with a title naming Withings support and historical syncs records, then 0.9.0 on 2026-09-17 whose title announces a Google Health pack and breaking changes. An operator copying the example ends up three releases behind, and one of the releases skipped is the one carrying the breaking changes. Whether historical syncs records altered existing data shapes is not stated here, so that belongs in the release notes rather than in an assumption.

Google Health is listed in both provider categories

Provider support is split into three groups. Cloud-based covers Garmin, Oura, Whoop, Suunto, Polar, Ultrahuman, Strava, Fitbit, Withings and Google Health. SDK-based covers Apple Health, Samsung Health and Google Health Connect. A third path is Apple Health XML import, where a full export can be uploaded, including large files through S3 multipart upload.

The overlap is worth settling before quoting a provider count at anyone. Google Health sits in the cloud list and Google Health Connect sits in the SDK list, so one vendor occupies two categories, and Apple Health appears twice as well, as an SDK source and as a file to upload. Coverage also differs by provider rather than being uniform: the documentation sends readers to separate pages for supported providers and for data coverage, and that second page is the place to find out whether a given metric arrives for a given device.

Postgres starts with a password that matches its own database name

The database service in `docker-compose.yml` is `postgres:18` with `POSTGRES_DB`, `POSTGRES_USER` and `POSTGRES_PASSWORD` all set to the same value, `open-wearables`, and the port published to the host as `${DB_PORT:-5432}:5432`. Nothing in the file overrides those defaults, so a first run on a machine that accepts them leaves a database reachable from outside the compose network with a password equal to the database name.

The same service carries a health check running `pg_isready` against that user and database every five seconds with five retries, and two volumes: a named `postgres_data` volume, and a read-only mount of `backend/scripts/init/create-svix-db.sql` into `docker-entrypoint-initdb.d`. That script is how the webhook service's own database gets created, and it runs only against a fresh volume. The Makefile's `reset_db` target states that it truncates all tables rather than dropping them, which is consistent with that volume surviving a reset.

Compose watch rebuilds the image when the dependency lock changes

The hot reload configuration is defined per path and per action. Changes under `backend/app`, `backend/scripts` and `backend/tests` are synced into the running container without restarting it, while `backend/migrations` and `backend/config/.env` are synced and then restart it, and `backend/uv.lock` triggers a full rebuild. Editing a model or a test is therefore instant, adding a migration restarts the API, and changing a pinned dependency re-images the service.

The app service also sets `pull_policy: never` on an image tagged `open-wearables-platform:latest`, which fits a build from source development loop, and `restart: on-failure`. Its configuration comes from `env_file: ./backend/config/.env`, the file the setup steps create by copying `.env.example`, with `DB_HOST` and `REDIS_HOST` overridden in the environment block so the API reaches the compose services by name instead of by localhost.

Every Makefile target drives the backend container except the tests

The Makefile defines one execution prefix, `DOCKER_EXEC = docker compose -f docker-compose.yml exec app`, and nearly every target goes through it. `migrate` and `downgrade` run `uv run alembic` inside the container, `seed` runs `uv sync --group dev` followed by `scripts/init/seed_activity_data.py`, and `reset_db` runs `scripts/reset_database.py`. `create_migration` is the one target that validates its input, failing when the `m="Description"` argument is missing.

Two details are easy to miss. The test target never uses the container:

test:	## Run the tests.
	cd backend && uv run pytest -v --cov=app

It changes into `backend` and runs pytest on the host, so the developer's own Python and dependency set decide whether the suite runs at all. And `seed` installs a dependency group inside the running container, so the sample data step mutates that container's environment rather than the checkout.

The MCP server reaches across users, sleep and menstrual cycles

The built-in MCP server is what makes the AI claim concrete. It works with Claude Desktop, Cursor and other MCP clients, and the data it can reach is listed openly: users, activity summaries, sleep, workouts, time series including heart rate, HRV, SpO2 and weight, and menstrual cycles. The examples are natural language questions, such as how a named person slept last week, or a comparison of the workouts of two users.

Those two examples describe a query surface that spans users rather than one person's own records, which is the point to weigh before enabling the server on an instance that holds more than your own data. The repository carries a top-level `mcp/` directory next to the backend and frontend, and the documentation is cut off mid-sentence while promising further AI capabilities, so the complete set of tools the server exposes is not settled by what is written here.

Seven assistant configurations sit beside the application code

The repository root holds `.ai/`, `.cursor/`, `.gemini/`, `.vscode/`, `.windsurfrules`, `.aider.md`, `GEMINI.md`, `CLAUDE.md` and `AGENTS.md`, together with `.coderabbit.yaml` and a `.pre-commit-config.yaml`. Several assistant tools configured in one repository turns their guidance into a consistency problem rather than a single file, and anyone changing build or migration conventions has to find which of those copies mentions them.

The rest of the layout is conventional for a three part project: `backend/`, `frontend/`, `mcp/`, `docs/`, a `contributing/` directory beside `CONTRIBUTING.md`, a `SECURITY.md`, a `Makefile` and a `docker-compose.yml`. The license is MIT and the last push to the main branch was 2026-10-02.

Editorial conclusion

Open Wearables is a credible base for a health product that would otherwise maintain one OAuth flow and one sync pipeline per wearable vendor, and the self-hosted route means the data stays on infrastructure you control. Before a first run, change the admin password from the developer portal rather than the environment file, because the seed will not do it for you, and replace the Postgres credentials that ship matching the database name. If you deploy it for real, choose a release tag deliberately: the example in the documentation, `0.7.0`, is three releases behind `0.9.0`, and that newer release announces breaking changes. If you enable the MCP server, decide who connects to it, since its documented data surface spans users, sleep, workouts, time series and menstrual cycles rather than one person's own records.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. the-momentum/open-wearables on GitHub