Deploying with Docker

Published images

Open Wearables publishes two production images to Docker Hub:

Image	Service	Port
`themomentum/open-wearables-backend`	FastAPI API + Celery worker/beat/flower	`8000`
`themomentum/open-wearables-frontend`	React frontend (TanStack Start, served by Nitro)	`3000`

The single backend image covers every backend role. The start command selects what the container runs:

Command	Role
`scripts/start/app.sh`	API server. Also applies database migrations and seed scripts on startup
`scripts/start/worker.sh`	Celery worker (data syncs, background jobs)
`scripts/start/beat.sh`	Celery beat (scheduler)
`scripts/start/flower.sh`	Flower (Celery monitoring UI, port `5555`)

Image tags

Both images share the same tag scheme. Choose a tag based on how much stability you need:

Tag	Points to	Use for
`latest`	The newest stable release	Quick trials, and deployments that always want the current stable version
`0.7.0` (exact version)	That release, immutably	Production - pin an exact version for repeatable, deliberate upgrades
`0.7` (major.minor)	The latest patch of that minor line	Following patch releases without manually bumping the version
`nightly`	The most recent build of `main`	Testing unreleased changes; not for production
`nightly-<sha>`	A specific nightly build, immutably	Reproducing or rolling back to an exact nightly, e.g. `nightly-a0b56b8`

Tags are produced by .github/workflows/publish-images.yml:

Nightly - a scheduled run at 02:00 UTC builds main and pushes nightly plus an immutable nightly-<sha>.
Release - publishing a GitHub release builds its git tag, pushes the version tags (0.7.0, 0.7), and moves latest. Pre-releases are published under their version tag but do not move latest.
Manual - the workflow can also be run by hand from the GitHub Actions UI. It requires a tag input and publishes that tag only - no nightly tags. Reserved names - latest, nightly, the whole nightly-* namespace, and release versions like 0.7.0/0.7 - are rejected, so a manual run can never move or overwrite them.

For production, pin an exact version tag (e.g. 0.7.0) rather than latest or nightly, so deployments are reproducible and upgrades are intentional.

What a deployment runs

A typical deployment consists of the application containers plus their backing services:

app - the API, from the backend image
celery-worker - background jobs, from the backend image
celery-beat - schedules recurring syncs, from the backend image
frontend - the web UI, from the frontend image
PostgreSQL - primary database
Redis - Celery broker and cache
flower (optional) - Celery monitoring, from the backend image
svix-server (optional) - only needed when outgoing webhooks are enabled; requires its own svix database

The backend reads all of its configuration from environment variables at runtime; backend/config/.env.example documents them. The frontend takes its API URL at runtime as well (see below). Neither image needs a per-environment rebuild.

The docker-compose.yml in the repository root is a development setup: it builds images from local source, hardcodes database credentials, and wires up hot reload via docker compose watch. Do not use it as a production template. For deployment, run the published images with your own orchestration—a Compose file you maintain, Kubernetes, or a managed platform such as Railway.

Example: Compose deployment

A baseline Compose stack using the published images. It uses the latest tag to stay copy-pasteable; pin an exact version tag like 0.7.0 for real deployments (see Image tags).

docker-compose.yml

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_DB: ${DB_NAME:-open-wearables}
      POSTGRES_USER: ${DB_USER:-open-wearables}
      POSTGRES_PASSWORD: ${DB_PASSWORD:?Set DB_PASSWORD in .env}
    volumes:
      - postgres_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:8
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
    restart: unless-stopped

  app:
    image: themomentum/open-wearables-backend:latest
    command: scripts/start/app.sh
    env_file:
      - ./.env
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped

  celery-worker:
    image: themomentum/open-wearables-backend:latest
    command: scripts/start/worker.sh
    env_file:
      - ./.env
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis
    depends_on:
      - app
    restart: unless-stopped

  celery-beat:
    image: themomentum/open-wearables-backend:latest
    command: scripts/start/beat.sh
    env_file:
      - ./.env
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis
    depends_on:
      - app
    restart: unless-stopped

  frontend:
    image: themomentum/open-wearables-frontend:latest
    environment:
      - VITE_API_URL=${VITE_API_URL:?Set VITE_API_URL in .env}
    ports:
      - "3000:3000"
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

Configuration

Copy backend/config/.env.example from the repository to .env next to the compose file. Compose reads the same file for variable interpolation, so DB_PASSWORD is defined once and shared by Postgres and the backend. The defaults in .env.example are development values. Override at least these for production:

Variable	Set to
`ENVIRONMENT`	`production`
`DB_PASSWORD`	a strong database password
`SECRET_KEY`	a long random secret, used to sign tokens
`ADMIN_PASSWORD`	password for the admin account seeded on first start
`CORS_ORIGINS`	your frontend origin, e.g. `["https://app.example.com"]`
`FRONTEND_URL`	public URL of the frontend
`API_BASE_URL`	public URL of the API, used for provider OAuth redirect URIs
`VITE_API_URL`	URL of the API as reached from the browser

VITE_API_URL is a frontend variable and is not part of .env.example—add it to the same .env. For a local trial of this stack, set it to http://localhost:8000; in production it is typically the same value as API_BASE_URL.

Running it

Pull the images

docker compose pull

Start the stack

docker compose up -d

The app container applies database migrations and seed scripts before the API starts.

Check service status

docker compose ps

All services should report Up, with db as Up (healthy).

Verify the API and frontend

curl -fsS http://localhost:8000/openapi.json > /dev/null && echo OK

Prints OK once the API is up (migrations can take a moment on first start). Then open http://localhost:3000 in a browser—the login page should load.

In practice you will put the API and frontend behind a reverse proxy with TLS instead of exposing the container ports directly. To add Flower, run another backend container with command: scripts/start/flower.sh and publish port 5555. To enable outgoing webhooks, add a svix-server service and a svix database; the development docker-compose.yml shows the wiring.

Configuring the frontend API URL at runtime

The frontend resolves its API URL at runtime, so the same published image works against any backend without rebuilding. Set VITE_API_URL as an environment variable on the frontend container. The Nitro server reads it at request time and injects it into the served HTML before the app loads:

docker run -p 3000:3000 \
  -e VITE_API_URL=https://api.client1.com \
  themomentum/open-wearables-frontend:latest

The same image with a different value points at a different backend—no rebuild:

docker run -p 3000:3000 \
  -e VITE_API_URL=https://api.client2.com \
  themomentum/open-wearables-frontend:latest

If VITE_API_URL is not set, it falls back to http://localhost:8000.

VITE_API_URL is a single variable used for both build-time (Vite inlines import.meta.env) and runtime configuration. When the same variable is set both in an .env file and via the container’s environment:, the container environment wins—so runtime always overrides any baked-in value.

How it works

Because the frontend is server-rendered (TanStack Start on Nitro), the value travels from the container env to the browser like this:

The Nitro server reads process.env.VITE_API_URL at request time.
It injects window.__APP_CONFIG__ = { apiUrl: "..." } into the HTML <head> before the app hydrates.
The API client reads that value. (Resolution order: injected runtime value → VITE_API_URL baked at build → http://localhost:8000.)

The logic lives in frontend/src/lib/api/runtime-config.ts.

Deploy to Railway — One-click managed deployment
Raw Payloads Storage — Backend runtime configuration example

Getting started

Architecture

Health Scores

Providers

Open Wearables Mobile App

Mobile SDK

MCP Server

Developer Guides

Configuration

Deployment

Support

Published images

Image tags

What a deployment runs

Example: Compose deployment

Configuration

Running it

Configuring the frontend API URL at runtime

How it works

​Published images

​Image tags

​What a deployment runs

​Example: Compose deployment

​Configuration

​Running it

​Configuring the frontend API URL at runtime

​How it works

​Related Guides

Published images

Image tags

What a deployment runs

Example: Compose deployment

Configuration

Running it

Configuring the frontend API URL at runtime

How it works

Related Guides