Frequently Asked Questions (FAQ)

This section provides answers to common questions about SparkyFitness.

General & Project Questions

What is SparkyFitness? SparkyFitness is a comprehensive fitness tracking and management application designed to help users monitor their nutrition, exercise, and body measurements. It provides tools for daily progress tracking, goal setting, and insightful reports to support a healthy lifestyle.
Is SparkyFitness free? Why a custom license? SparkyFitness uses a custom license to retain commercial rights. Building and maintaining the project requires significant resources (hardware, developer accounts, infrastructure, AI tools, etc.). If companies commercially host the project, it is reasonable to ask them to obtain permission or contribute back.
Recently, several hosting providers began offering SparkyFitness. While some reached out to discuss partnerships and revenue sharing, others did not. This reinforced the decision to keep commercial hosting under a separate license rather than adopting a standard open-source license that would relinquish that control.
The intention is not to prevent individuals from using or self-hosting the project, but to ensure that if SparkyFitness becomes commercially valuable, the project itself can remain sustainable. The licensing model may be revisited as the project grows, but this currently represents the fairest balance.
Will SparkyFitness be free forever? There are no plans to charge self-hosted users. However, maintaining the project involves ongoing expenses such as development infrastructure, developer license fees, and AI services. If you find SparkyFitness valuable, consider sponsoring the project to help keep it sustainable and free for everyone.
Is my data private? Yes. SparkyFitness does not collect or transmit any of your personal data; everything is stored locally on your server. However, third-party services you configure (such as OpenAI or Google Gemini AI APIs, external data providers) may process and store data according to their respective policies.
What is the goal of SparkyFitness? The goal is to build SparkyFitness into a comprehensive, "one-stop" health and wellness solution. Rather than switching between multiple apps, we want SparkyFitness to cover calorie tracking, exercise and workout logging, wellness metrics, medications, and mental health in a single unified platform.
What features can I expect next, and how are updates prioritized? We prioritize bug fixes above all else to ensure the application remains stable, which is why bugs are addressed and closed as quickly as possible. For new features and enhancements, we prioritize based on impact (features requested by many users), followed by the oldest pending requests.
My GitHub request was closed as completed, but I don't see the changes in my app. Why? When an issue or enhancement request is closed as completed, the code has been successfully merged into our main branch. These changes will become available in the next official release. You can verify this by checking if a Pull Request (PR) is attached to the closed item.

Setup & Deployment

How do I install SparkyFitness? Please refer to the Installation Guide for detailed instructions on how to install SparkyFitness using various methods.
What are the system requirements? If you deploy using Docker, the container package includes everything you need to run the application. However, if you are installing directly from source or utilizing other deployment methods, please refer to their respective installation guides for specific system and package dependencies.
Can I use my own external PostgreSQL database? Yes, you can run SparkyFitness with an external database. Please refer to our External Database Guide for detailed configuration instructions.
Why is the installation so complex? We are actively working on improving the installation experience. If you have suggestions or ideas to simplify the setup, please feel free to raise a Pull Request or open a discussion/issue on our GitHub repository.
What should I set for SPARKY_FITNESS_FRONTEND_URL in my .env? Set SPARKY_FITNESS_FRONTEND_URL to the exact URL you use to access the SparkyFitness frontend in your web browser (e.g., https://192.168.1.100:3004 or https://fitness.yourdomain.com).
Does the mobile app support HTTP? No. While the web interface can work over HTTP, the mobile app requires HTTPS to function (for camera access, barcodes, and other native features required by Apple and Google app store publishing guidelines). Because health data is highly sensitive, we do not support or recommend running your public-facing instance over HTTP. https://developer.android.com/health-and-fitness/health-connect/availability https://developer.apple.com/documentation/healthkit/protecting-user-privacy
Can I migrate my data from Flo, MyFitnessPal, or other apps? While direct API integration with some platforms (like Hevy) is supported, many commercial apps (like Flo or MyFitnessPal) require enterprise credentials and restrict API access for self-hosted apps. However, SparkyFitness provides robust CSV import tools for Food, Exercises, and Check-ins. Support for importing Period, Pregnancy, and Medication history is planned for future updates.

Mobile App

Do you have a mobile app? Yes! Please refer to our Android Mobile App Guide and Apple Health Integration Guide for detailed setup instructions.
- Android: APKs are available on the GitHub Releases page. You can also join our Google Play Store Closed Testing group via the link provided on the GitHub Wiki.
- iOS: The app is live on the Apple App Store, and beta builds are accessible via Apple TestFlight.
Why are the Google closed testing or App Store builds outdated? The Android APK on GitHub is updated automatically with every release. We try to keep Google Closed Testing and Apple TestFlight builds updated alongside it, though they usually take 1–2 days to be approved by Google/Apple. Production App Store releases, on the other hand, are pushed on a slower cycle (typically every couple of months).
How do I integrate with Gadgetbridge? You can sync your wearable data from Gadgetbridge to Android's Health Connect first, and then use the SparkyFitness mobile app to sync those metrics into SparkyFitness. For detailed instructions, refer to the Gadgetbridge Health Connect Integration Guide.
Do you have a smartwatch companion app (Apple Watch or Wear OS)? A dedicated smartwatch companion app is on our development roadmap/To-Do list.

Features & Customization

How do I sync with Garmin? First, ensure you enable the Garmin integration service in your docker-compose.yml file. Once enabled, log in to the SparkyFitness Web UI, navigate to the External Data Providers settings section, and link your Garmin Connect account.
How do I enable the Chatbot or Model Context Protocol (MCP)? You can enable the AI chatbot by configuring your LLM provider credentials in the Web UI under your account settings tab. The MCP API is exposed globally and can be reached at the /mcp backend endpoint.
What external food and exercise/health data providers are supported? SparkyFitness integrates with several popular health, fitness, and recipe APIs:
- Food & Recipes: OpenFoodFacts, USDA, FatSecret, Yazio, Swiss Food Database, Mealie, Tandoor, Nourish, and Nutritionix.
- Wearables & Fitness Services: Garmin Connect, Polar, Withings, Hevy, Wger, Apple Health (via the iOS app), Google Health API and Google Health Connect (via the Android app, which allows bridging data from Google Fit, Samsung Health, Gadgetbridge, and others).
Where do I configure external data/API providers? External lookup providers (like OpenFoodFacts, FatSecret, or Nutritionix) can be configured within the Food & Exercise Providers section under your admin settings tab.
Can I add custom nutrition / nutrients? Yes! You can add custom nutrients via the settings tab. Once configured, you can map these custom nutrients to your provider fields when importing new foods.
Does SparkyFitness have its own food database? No, it does not package a standalone food database. Some default sources are configured out of the box, but for advanced lookups requiring API keys (like FatSecret or Nutritionix), the instance administrator must configure them in the settings.

Troubleshooting

"Invalid key length" error during setup This error typically indicates that your SPARKY_FITNESS_API_ENCRYPTION_KEY in your .env file is not correctly configured. Ensure it is a 64-character hexadecimal string. You can generate a valid key using:
```
openssl rand -hex 32
```
Alternatively, using Node:
```
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Locked out due to MFA/2FA issues or invalid recovery codes If you are locked out of your account, you can disable MFA directly via your database. Connect to your database container (psql) and run:

-- 1. Disable MFA flags on users
UPDATE "user" 
SET 
    two_factor_enabled = false,
    mfa_totp_enabled = false,
    mfa_email_enabled = false,
    mfa_enforced = false,
    email_mfa_code = NULL,
    email_mfa_expires_at = NULL;

-- 2. Clear configured TOTP secrets and backup codes
TRUNCATE TABLE "two_factor";

-- 3. Disable the global mandatory MFA setting
UPDATE "global_settings" SET mfa_mandatory = false WHERE id = 1;

Additionally, ensure BETTER_AUTH_SECRET is set in your .env to prevent legacy payload decryption issues after a server restart.

OIDC setup fails with "Error fetching OIDC discovery document" or connection timeouts If your OIDC provider (e.g., Authentik, Authelia) is running locally on the same host or local network, the SparkyFitness server container may fail to resolve or connect to the provider's local domain name. To resolve this, map the OIDC domain to your host's local IP address by adding an extra_hosts configuration to the sparkyfitness-server service in your docker-compose.yml:
```
services:
  sparkyfitness-server:
    # ...
    extra_hosts:
      - "auth.yourdomain.com:192.168.1.100" # Replace with your OIDC domain and local host IP
```
Why is my OpenFoodFacts search or lookup erroring out? This is typically caused by rate-limiting on OpenFoodFacts' public API endpoints. OpenFoodFacts searches perform much more reliably if you supply your own credentials. You can register for an account and add your OpenFoodFacts credentials under the External Data Providers settings section in the Web UI.
Why is my Android health data not syncing properly to SparkyFitness? SparkyFitness uses Android's Health Connect to sync fitness metrics. For data to flow successfully, the source health apps must first sync their data into Health Connect. For example, many Samsung devices require a third-party application (such as Health Sync) to bridge data from Samsung Health into Health Connect before SparkyFitness can retrieve it.
My self-hosted LLM/chatbot is slow or failing inside SparkyFitness, but works fast outside of it? By default, Ollama initializes with a context window of 4KB. The SparkyFitness chatbot and MCP integrations utilize over 35 tools and process complex schema payloads. If your VRAM is limited, the context processing will slow down significantly. Ensure you increase your runner's context window limit and allocate enough GPU VRAM to handle the larger payloads.

Cloud & Hosting

Is there a hosted version available? No, we officially support and maintain only the self-hosted version. However, you can use third-party cloud providers (such as Pikapod or Zenith Hosting) to host your instance. Please perform your own due diligence before selecting a third-party cloud host.

Getting Help

If you can't find the answer to your question here, please consider:

Joining our Discord community: A great place to ask questions and get help from other users and developers.
Checking GitHub Discussions: Look for existing discussions or start a new one to get support.
Reporting an issue: If you believe you've found a bug, please report it on our GitHub Issues page.

Community Guides

Help Me!