Deploy and Host SparkyFitness on Railway

SparkyFitness is a self-hosted fitness and nutrition tracker in the spirit of MyFitnessPal. Log food with barcode and photo recognition, track workouts, water intake, body measurements and progress photos, set goals, and chat with Sparky, its built-in AI assistant. Version 1.6 also ships an MCP endpoint, so AI assistants like Claude can read and write your fitness data with your permission.

About Hosting SparkyFitness

This template deploys the current SparkyFitness release (v1.6.1) as three services: a Postgres 18 database, the API server, and the web app served by nginx. Both the database and the server get persistent volumes, so your data, uploaded photos and in-app backups survive redeploys. All secrets (database passwords, session signing key, data encryption key) are generated for you at deploy time, including the 64 character hex encryption key the server requires. The web app proxies API traffic to the server over Railway's edge, which keeps the app reachable across server redeploys with zero configuration.

Common Use Cases

Personal or household calorie counting and macro tracking without a subscription or ads
Workout, water, sleep, body measurement and progress photo logging in one private place
Connecting AI assistants to your nutrition data through the built-in MCP endpoint
Syncing wearables and services like Garmin, Fitbit, Withings, Strava, Polar and Oura through the in-app integrations

Dependencies for SparkyFitness Hosting

Deployment Dependencies

Upstream project: https://github.com/CodeWithCJ/SparkyFitness
Docker images: codewithcj/sparkyfitness:v1.6.1, codewithcj/sparkyfitness_server:v1.6.1, postgres:18.3-alpine

Implementation Details

First boot takes about a minute while the server runs database migrations.

Getting started:

Open the web app URL and sign up. The first account created gets admin rights automatically.
If you filled in the optional admin email at deploy time, the account with that email is also promoted to admin on every server start.
Once your household has accounts, disable open signups in Admin settings.

Two secrets deserve care:

BETTER_AUTH_SECRET signs sessions and encrypts two factor auth. Never change it after anyone enables 2FA, or they are locked out permanently.
SPARKY_FITNESS_API_ENCRYPTION_KEY encrypts stored third party API credentials. Rotating it means re-adding those connections.

Optional variables you can add to the server service any time: SMTP for password resets (SPARKY_FITNESS_EMAIL_HOST, PORT, SECURE, USER, PASS, FROM), OIDC single sign-on (SPARKY_FITNESS_OIDC_*), and AI photo food logging (VISION_API_PROVIDER plus VISION_API_KEY for Gemini, OpenAI or Anthropic).

The API server has its own public URL on purpose: the web app proxies to it over Railway's edge so the app keeps working across server redeploys. Every API endpoint requires login, and the API docs are login gated by default.

The Garmin sync microservice is not included; upstream still marks it work in progress. It can be added as a fourth service later without touching this stack.

Why Deploy SparkyFitness on Railway?

Railway gives SparkyFitness exactly what a self-hosted health app needs: private networking between app and database, persistent volumes for your photos and backups, automatic TLS on your public URL, and one click deploys of the whole three service stack. Your health data stays in your own project, on infrastructure you control, for pennies a day.