How We Made Open Wearables Deployable in One Click

1. The Setup Problem

Running Open Wearables in a real environment requires seven separate services working together. You need PostgreSQL for data storage, a FastAPI backend, a React frontend, Redis as a message broker, a Celery worker for background jobs, Celery Beat for scheduled syncing, and Flower to monitor the task queue.

Before this Railway template existed, you provisioned each service manually. That meant writing or adapting a Compose file, setting environment variables per service, wiring networking between them, and making sure credentials were consistent across all the configurations. That is before writing any application code.

The setup step is not complex in the sense that any individual piece is hard to understand. It is complex because there are many pieces, and getting them all right takes time. For a developer who wants to evaluate whether Open Wearables fits their use case, that time investment is hard to justify before seeing the platform work.

2. Why Activation Friction Is a Growth Problem?

Most developers who discover an open source project through GitHub, a blog post, or a conference talk never actually run it. The gap between "found it interesting" and "it is running" is where most potential contributors disappear.

Infrastructure requirements act as a filter at the top of the funnel. Someone who does not get past the setup step cannot file issues, suggest features, report bugs, or submit pull requests. They may star the repo, but that is the extent of their engagement.

Open source projects do not have onboarding emails or sales calls. The product experience is the funnel. If the first real interaction with the project is a multi-service configuration task, you lose people who would have contributed if they had reached the point where it works.

3. What the Railway Template Does?

The Railway deploy template provisions all seven services in a single click. Railway handles networking between them and injects connection strings as environment variables. You do not configure which port PostgreSQL listens on or how the Celery worker finds Redis. The template handles that.

A default admin account is created on first startup. The default credentials are intentionally insecure (admin@admin.com / secret123) and need to be changed before the instance is exposed to any network. You can set ADMIN_EMAIL and ADMIN_PASSWORD as environment variables before the first deploy to skip the insecure defaults entirely.

Watch the full deploy process - from clicking the Railway template to a running instance with all seven services online.

‍

4. What Actually Gets Deployed

The template provisions these seven services:

PostgreSQL

Stores user accounts, wearable health data, and API keys. Railway manages the instance and injects the connection string into the backend automatically.

Backend (FastAPI)

The API layer. It normalizes data from different wearable providers into a consistent format and exposes it through a unified interface. Provider OAuth flows are handled here.

Frontend (React)

The admin dashboard for managing users and provider connection setup. The frontend communicates with the backend through the VITE_API_URL environment variable.

Redis

Serves two roles: message broker for Celery task routing, and caching layer for the backend. Connection details are auto-injected.

Celery Worker

Processes background jobs. The primary work is syncing data from wearable providers after a user connects their account.

Celery Beat

Runs scheduled tasks on a timer. It triggers periodic syncs so wearable data stays current without requiring manual requests.

Flower

A web interface for monitoring the Celery task queue. Useful for checking whether sync jobs are running, debugging failed tasks, and inspecting queue depth.

All networking between services is configured by the template. You manage each service through Railway's dashboard, where you have independent access to logs, environment variables, and deployment controls.

Here's what the admin interface looks like once everything is running.

5. What You Still Need to Configure

The template provisions a running instance. It does not configure provider integrations.

OAuth credentials

Each wearable provider requires its own OAuth application credentials. You register a developer application with Garmin's portal, Polar's API console, Whoop's developer program, and any other providers you want to support. Each registration process is different. Once you have the credentials, add them to the Backend service environment variables. The full list of required variable names per provider is in the documentation at docs.openwearables.io/deployment/railway.

Admin credentials

Change the default admin account before exposing the instance to any network. Set ADMIN_EMAIL and ADMIN_PASSWORD in the Backend service environment variables. If you set them before the first deploy, the insecure defaults are never used.

Once your admin account is configured, here's how to generate an invitation code for mobile app authentication.

Custom domain (optional)

Railway assigns a default domain in the format projectname.up.railway.app. If you need a custom domain, configure it on the Frontend service in Railway, then update VITE_API_URL on the frontend and CORS_ORIGINS on the backend to match.

6. Constraints Worth Knowing

Check GitHub for the current version and release notes. APIs may change before v1.0. If you are building an application on top of Open Wearables, pin to a specific version and review release notes before upgrading.

Self-hosting on Railway is not free. Railway charges for compute and storage based on usage. You are also responsible for PostgreSQL backups, service monitoring, and staying current with Open Wearables updates. The template handles initial provisioning; ongoing infrastructure management is yours.

OAuth setup cannot be automated. Each wearable provider controls their own developer registration process, and credentials are application-specific. No open source template can bundle these.

7. Getting Started

1. Go to railway.app
2. Open the template marketplace and search for Open Wearables
3. Click Deploy
4. Set ADMIN_EMAIL and ADMIN_PASSWORD before the first startup
5. After deploy, add OAuth credentials for the providers you want to support
6. Configure a custom domain if your use case requires it

Full documentation: docs.openwearables.io/deployment/railway

8. More Resources

• GitHub: github.com/the-momentum/open-wearables
• Documentation: docs.openwearables.io
• Community Discord

If you deploy it and run into a problem, open a GitHub issue with the service name and the relevant log output. If you want to ask questions before deploying, join the Discord.

‍

‍