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

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.
  • 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 or 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. This allows for more secure secret management in containerized environments.
  • JWT_SECRET: A secret key for signing JSON Web Tokens (JWTs). Make this a long, random, and secure string. You can generate one using openssl rand -base64 32 or node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
    • JWT_SECRET_FILE: (Optional) Path to a file containing the JWT secret. Useful for Docker Swarm/Kubernetes secrets. Similar to the encryption key, when this variable is set, the application will read the JWT secret from the specified file path.

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

  • SPARKY_FITNESS_SERVER_HOST: The hostname or IP address of the backend server. This variable is primarily used by the Internal Nginx proxy (not to be confused with your proxy manager) in the frontend container to correctly route API requests to the backend service. For Docker Compose, this defaults to sparkyfitness-server (the service name for inter-container communication). If running outside Docker Compose, you would typically set this to localhost or the server's IP.
  • SPARKY_FITNESS_SERVER_PORT: The server port (e.g., 3010). This is the port on which the backend server listens. It defaults to 3010 if not explicitly set. This variable is also used by the Internal Nginx proxy (not to be confused with your proxy manager) in the frontend container.
  • 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.
  • Email Settings: Configure these variables if you want to enable email notifications (e.g., for password resets). If not configured, email functionality will be disabled.
    • SPARKY_FITNESS_EMAIL_HOST: SMTP host for sending emails (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.
  • Garmin Integration: If you require Garmin integration, uncomment the relevant section from the docker-compose.yml file and configure the following variables:
    • GARMIN_MICROSERVICE_URL: The URL for the Garmin microservice (e.g., http://sparkyfitness-garmin:8000).
    • GARMIN_SERVICE_PORT: This is used for Garmin Connect synchronization. Make sure this matches with GARMIN_MICROSERVICE_URL.
    • GARMIN_SERVICE_IS_CN: Set to true for China region. Everything else should be false. Optional - defaults to false.
Table of Contents