Environment Variables

This document provides a comprehensive list and detailed descriptions of all environment variables used by SparkyFitness. Proper configuration of these variables is crucial for the application to function as expected.

For a complete list of all available variables and their detailed descriptions, please refer to the example environment file: .env.example on GitHub

Important Note for Docker Compose Users:
For an environment variable defined in your .env file to be recognized by the application running inside a Docker container, it must be explicitly passed to that service in your docker-compose.yml file. If you add a new variable to your .env file that is not already present in the environment: section of the sparkyfitness-server (or sparkyfitness-garmin) service, the application will not see it.

Essential Configuration

The following environment variables are mandatory and must be supplied for the application to start correctly. Failure to provide these will result in the server failing to launch.

  • SPARKY_FITNESS_DB_NAME: Your desired PostgreSQL database name (e.g., sparkyfitness_db).
  • SPARKY_FITNESS_DB_USER: Your desired PostgreSQL database user (e.g., sparky). This user is used for DB initialization and migrations.
  • SPARKY_FITNESS_DB_PASSWORD: A strong password for your PostgreSQL database. This shouldn't be changed after initial setup. If you need to change it, you will need to update the password in the database and update this env variable.
  • SPARKY_FITNESS_APP_DB_USER: Application database user with limited privileges. It can be changed any time after initialization.
  • SPARKY_FITNESS_APP_DB_PASSWORD: Password for the application database user.
  • SPARKY_FITNESS_FRONTEND_URL: The public URL of your frontend (e.g., http://localhost:8080 for local testing, or your domain like https://fitness.example.com for production). This is crucial for CORS security.
  • SPARKY_FITNESS_API_ENCRYPTION_KEY: A 64-character hex string for data encryption. You can generate one using:
    • openssl rand -hex 32
    • node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    • SPARKY_FITNESS_API_ENCRYPTION_KEY_FILE: (Optional) Path to a file containing the encryption key. Useful for Docker Swarm/Kubernetes secrets. When this variable is set, the application will read the encryption key from the specified file path, allowing for more secure secret management in containerized environments.
  • BETTER_AUTH_SECRET: A secret key used by Better Auth to sign sessions and tokens. Make this a long, random, and secure string. You can generate one using:
    • openssl rand -hex 32
    • node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

    • !CAUTIONCRITICAL for 2FA/TOTP: This secret is used to encrypt Two-Factor Authentication (2FA) data in the database. If you change this variable after users have enabled 2FA, the server will lose access to their codes, and all 2FA users will be locked out of their accounts. This variable must be set to a persistent value during initial setup and should never be changed. If you must change it, you must ensure that ALL users have disabled Two-Factor Authentication (TOTP) first.

Mandatory Volume Paths

These paths define where Docker volumes will store persistent data on your host. These are mandatory to prevent data loss if containers are removed. You can either define them in the .env file or directly in the docker-compose.yml.

  • DB_PATH: Path for PostgreSQL database data (e.g., ../postgresql).
  • SERVER_BACKUP_PATH: Path for server backups (e.g., ./backup).
  • SERVER_UPLOADS_PATH: Path for profile pictures and exercise images (e.g., ./uploads).

Optional Configuration

The following variables are optional and can be used to customize your SparkyFitness installation.

Server Side Variables

These variables control backend behavior and should be passed to the sparkyfitness-server service in your docker-compose.yml.

  • SPARKY_FITNESS_DISABLE_EMAIL_LOGIN: Set to true to disable email/password login on the login page (overridden by SPARKY_FITNESS_FORCE_EMAIL_LOGIN).
  • SPARKY_FITNESS_LOG_LEVEL: Logging level for the server (e.g., INFO, DEBUG, WARN, ERROR).
  • NODE_ENV: Node.js environment mode (e.g., development, production, test). Set to production for deployment to ensure optimal performance and security.
  • TZ: Server timezone. Use a TZ database name (e.g., America/New_York, Etc/UTC).
  • SPARKY_FITNESS_DISABLE_SIGNUP: Set to true to disable new user registrations.
  • SPARKY_FITNESS_ADMIN_EMAIL: Set the email of a user to automatically grant admin privileges on server startup. If not set, no admin user will be created automatically.
  • SPARKY_FITNESS_FORCE_EMAIL_LOGIN: Set to true to force email/password login to be enabled, overriding any in-app settings. This is a fail-safe to prevent being locked out if OIDC is misconfigured.
  • ALLOW_PRIVATE_NETWORK_CORS: Set to true to allow Cross-Origin Resource Sharing (CORS) from private network addresses (e.g., 192.168.x.x, 10.x.x.x, 127.0.0.1, localhost). Use with caution.
  • SPARKY_FITNESS_EXTRA_TRUSTED_ORIGINS: A comma-separated list of additional URLs that Better Auth should trust (e.g., http://192.168.1.175:8080). Use this if you are accessing the app from specific local IPs and ALLOW_PRIVATE_NETWORK_CORS is enabled.
  • SPARKY_FITNESS_DB_HOST: The hostname of the PostgreSQL database. For Docker Compose, this defaults to sparkyfitness-db (the service name). Only change this if you are using an external database server.
  • SPARKY_FITNESS_DB_PORT: Controls the host port exposed for external database access (e.g., pgAdmin). Important: Inside Docker, containers always communicate on port 5432. Changing this value in .env will not affect container-to-container communication unless you are using an external database server. To use this, you must also uncomment the ports section under the sparkyfitness-db service in your docker-compose.yml file.
  • SPARKY_FITNESS_SERVER_HOST: The hostname or IP of the backend server. Primarily used by the internal Nginx proxy (not to be confused with your proxy manager) in the frontend container to route API requests. For Docker Compose, this defaults to sparkyfitness-server.
  • SPARKY_FITNESS_SERVER_PORT: The server port (e.g., 3010). Defaults to 3010. This is also used by the internal Nginx proxy (not to be confused with your proxy manager) in the frontend container.

Email Settings (Server Side)

Configure these variables to enable email notifications (e.g., for password resets). If not configured, email functionality will be disabled.

  • SPARKY_FITNESS_EMAIL_HOST: SMTP host (e.g., smtp.example.com).
  • SPARKY_FITNESS_EMAIL_PORT: SMTP port (e.g., 587).
  • SPARKY_FITNESS_EMAIL_SECURE: Use true for TLS/SSL, false for plain text.
  • SPARKY_FITNESS_EMAIL_USER: Your email username.
  • SPARKY_FITNESS_EMAIL_PASS: Your email password.
  • SPARKY_FITNESS_EMAIL_FROM: The 'from' email address.

Rate Limiting (Server Side)

API keys are rate-limited to prevent abuse. These must be passed to sparkyfitness-server.

  • SPARKY_FITNESS_API_KEY_RATELIMIT_WINDOW_MS: Time window in milliseconds. Defaults to 60000 (1 minute).
  • SPARKY_FITNESS_API_KEY_RATELIMIT_MAX_REQUESTS: Maximum number of requests allowed per window. Defaults to 100.

OIDC Configuration (Server Side)

These variables configure the environment-based OIDC provider and must be passed to the sparkyfitness-server service.

When the following are set, an OIDC provider is created or updated at startup and used with the existing SSO flow.

  • SPARKY_FITNESS_DISABLE_EMAIL_LOGIN: Set to true to disable email/password login on the login page (overridden by SPARKY_FITNESS_FORCE_EMAIL_LOGIN).
  • SPARKY_FITNESS_OIDC_AUTH_ENABLED: Set to true to enable OIDC login, overriding the value from Admin > Authentication Settings.
  • SPARKY_FITNESS_OIDC_ISSUER_URL: Issuer URL (e.g. https://auth.example.com). Discovery URL is derived as issuer + /.well-known/openid-configuration. Required for env provider upsert.
  • SPARKY_FITNESS_OIDC_CLIENT_ID, SPARKY_FITNESS_OIDC_CLIENT_SECRET: Client credentials from your IdP. Required for env provider upsert.
  • SPARKY_FITNESS_OIDC_PROVIDER_SLUG: URL-safe provider id (e.g. authentik). Required for env provider upsert.
  • SPARKY_FITNESS_OIDC_PROVIDER_NAME: Display name for the provider (optional; defaults to slug).
  • SPARKY_FITNESS_OIDC_SCOPE: Space-separated OIDC scopes (optional; defaults to openid email profile).
  • SPARKY_FITNESS_OIDC_AUTO_REGISTER: Set to true to automatically create a new user account on first OIDC login (optional; defaults to true).
  • SPARKY_FITNESS_OIDC_LOGO_URL: URL to a custom logo for the provider (optional).
  • SPARKY_FITNESS_OIDC_DOMAIN: Organization domain for restricted access (optional; defaults to slug.env).
  • SPARKY_FITNESS_OIDC_TOKEN_AUTH_METHOD: Authentication method for the token endpoint (optional; defaults to client_secret_post).
  • SPARKY_FITNESS_OIDC_ID_TOKEN_SIGNED_ALG: Algorithm used to sign the ID token (optional; defaults to RS256).
  • SPARKY_FITNESS_OIDC_USERINFO_SIGNED_ALG: Algorithm used to sign the UserInfo response (optional; defaults to none).
  • SPARKY_FITNESS_OIDC_TIMEOUT: Request timeout in milliseconds (optional; defaults to 30000).
  • SPARKY_FITNESS_OIDC_AUTO_REDIRECT: Set to true to allow auto-redirect to the single OIDC provider when email login is disabled.
  • SPARKY_FITNESS_OIDC_ADMIN_GROUP: Group/claim value from your IdP for admin role mapping. Configure your IdP to send this in token claims; it is used to automatically grant admin privileges.
  • ALLOW_PRIVATE_NETWORK_CORS: Set to true to allow Cross-Origin Resource Sharing (CORS) from private network addresses (e.g., 192.168.x.x, 10.x.x.x, 127.0.0.1, localhost). This allows standard browser requests from local IPs. Use with caution.
  • SPARKY_FITNESS_EXTRA_TRUSTED_ORIGINS: A comma-separated list of additional URLs that Better Auth should trust (e.g., http://192.168.1.175:8080,http://10.0.0.5:8080). Use this if you are accessing the app from specific local IPs on your network and ALLOW_PRIVATE_NETWORK_CORS is enabled.

Garmin Integration

If you require Garmin integration, ensure GARMIN_MICROSERVICE_URL is passed to both the sparkyfitness-server and sparkyfitness-garmin services. The other two variables are for the sparkyfitness-garmin service.

  • GARMIN_MICROSERVICE_URL: The URL for the Garmin microservice (e.g., http://sparkyfitness-garmin:8000).
  • GARMIN_SERVICE_PORT: Used for Garmin Connect synchronization. Must match GARMIN_MICROSERVICE_URL.
  • GARMIN_SERVICE_IS_CN: Set to true for China region. Defaults to false.
Table of Contents