Frequently Asked Questions¶

Common questions about Tempo.

General¶

What is Tempo?¶

Tempo is a self-hostable running tracker that serves as a privacy-first alternative to Strava. It allows you to track your workouts while keeping all data on your own infrastructure.

Is Tempo free?¶

Yes, Tempo is open source and free to use. It's licensed under the MIT License.

Do I need to pay for hosting?¶

No, you can host Tempo on your own infrastructure. You only need to pay for your own server/hosting if you choose to use cloud services.

Can I use Tempo without technical knowledge?¶

Yes! The Docker Compose quick start makes it easy to get started. However, some technical knowledge helps for production deployment and troubleshooting.

Installation¶

What are the system requirements?¶

Minimum: 1 CPU core, 2GB RAM, 10GB storage
Recommended: 2+ CPU cores, 4GB+ RAM, 50GB+ storage

Do I need Docker?¶

Docker Compose is the easiest way to run Tempo, but you can also run services individually if you prefer.

Can I run Tempo on Windows/Mac/Linux?¶

Yes, Tempo runs on all platforms that support Docker. The backend is .NET (cross-platform), and the frontend is Next.js (Node.js).

How long does installation take?¶

With Docker Compose, installation takes just a few minutes. Most of the time is spent downloading images.

Features¶

What file formats does Tempo support?¶

Tempo supports: - GPX (.gpx) - FIT (.fit, .fit.gz) - Strava CSV (.csv)

Can I import from Strava?¶

Yes! You can: - Import individual GPX files from Strava on the Import page (file upload only) - Bulk import your entire Strava history using a Strava data export (first-run onboarding, or Settings → Migrate / restore)

What is first-run onboarding?¶

After registration, Tempo guides you through optional Tempo restore, essential settings (units and heart rate zones), and an optional Strava archive. App routes stay gated until setup finishes. See First-run onboarding.

Will upgrading force me through onboarding again?¶

No. Existing accounts are backfilled as already completed when onboarding ships. There is no “run setup again” entry in Settings.

I skipped Strava during onboarding. Can I import a Strava ZIP later?¶

Yes. Open Settings → Data Management → Migrate / restore → Import Strava archive. Day-to-day GPX/FIT files stay on the Import page.

Does Tempo sync with my devices?¶

Tempo doesn't automatically sync with devices. You need to export files from your device and import them into Tempo.

Can I export my data from Tempo?¶

Yes. Use Settings → Export to download a ZIP of workouts, routes, splits, time series, media, shoes, settings, and best efforts. Restore a previous export under Settings → Migrate / restore. See the Settings export/import guide and Backup and Restore. You can also access PostgreSQL and the media/ directory directly.

Does Tempo work offline?¶

Yes! Once installed, Tempo runs entirely on your infrastructure and doesn't require internet connectivity (except for weather data, which is optional).

Data and Privacy¶

Where is my data stored?¶

All data is stored locally on your infrastructure: - Database: PostgreSQL (in Docker volume or your PostgreSQL instance) - Media files: Filesystem in media/ directory

Does Tempo send data to external services?¶

Tempo only contacts external services for: - Weather data (Open-Meteo API) - based on workout location and time - No other data is sent externally

Can I backup my data?¶

Yes! See the Backup and Restore guide for instructions.

How do I migrate to a new server?¶

Backup database and media files
Install Tempo on new server
Restore database and media files
Update configuration if needed

Technical¶

What database does Tempo use?¶

PostgreSQL 16. The database runs in Docker or can be a separate PostgreSQL instance.

Can I use a different database?¶

No, Tempo is designed for PostgreSQL and uses PostgreSQL-specific features (JSONB, etc.).

How do I update Tempo?¶

Pull new Docker images
Update docker-compose.prod.yml with new image tags
Restart services
Database migrations run automatically

Can I customize Tempo?¶

Yes! Tempo is open source. You can modify the code to suit your needs.

How do I contribute?¶

See the Contributing Guide for details.

Troubleshooting¶

Why can't I register?¶

Registration is only available when no users exist. After the first user is created, registration is locked for security.

Why am I stuck on the setup / onboarding screen?¶

Until onboarding completes, every app route redirects to the wizard. Finish restore or essentials (and answer the Strava question), or use Skip for now after a failed Strava job. Logout is available from the onboarding shell. See First-run onboarding.

Why is my import slow?¶

Large files take longer to process. Very large imports (hundreds of workouts) may take several minutes.

Why don't I see my route on the map?¶

Routes require GPS data in the workout file. Some files may not contain GPS coordinates.

Why is weather data missing?¶

Weather data requires: - Valid location (latitude/longitude) in workout - Valid timestamp - Internet connectivity (for API call)

How do I reset my password?¶

There is no email or login-page reset. An operator with host access sets a new passphrase via the API command (same 16–64 character rules as registration). Outstanding sessions are invalidated; log in again. Registration stays locked — this is not how you add a second person.

docker compose exec -it api dotnet Tempo.Api.dll reset-password

Scripts (no TTY):

docker compose exec -T api dotnet Tempo.Api.dll reset-password --password-stdin

Production Compose file: add -f docker-compose.prod.yml. If the API container is not running: docker compose run --no-deps --rm api reset-password (the image entrypoint already prefixes dotnet Tempo.Api.dll). On a bare API host, run dotnet Tempo.Api.dll reset-password from the API working directory.

Forgot the username: omit --username when there is exactly one account (the command prints the name it reset). Last resort: SELECT "Username" FROM "Users"; — do not hand-write a BCrypt hash.

If the session expires immediately after a successful login, that is a cookie/HTTPS issue, not a forgotten passphrase. See Authentication Problems.

Support¶

Where can I get help?¶

How do I report a bug?¶

Create an issue on GitHub with: - Description of the bug - Steps to reproduce - Expected vs actual behavior - Environment details

Can I request a feature?¶

Yes! Create a feature request on GitHub Issues.