Environment variables are the primary configuration mechanism for SparkyFitness. They control everything from database credentials and secret keys to email delivery, CORS policy, and optional integrations. For a Docker Compose deployment the variables live in aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/CodeWithCJ/SparkyFitness/llms.txt
Use this file to discover all available pages before exploring further.
.env file in the same directory as your docker-compose.yml. For Kubernetes deployments they are managed through Helm values and Kubernetes Secrets.
Required Variables
The following variables are mandatory. The server will refuse to start if any of them are missing or empty.PostgreSQL database name. Choose a name for your database, for example
sparkyfitness_db. Must match the database you create during setup.PostgreSQL superuser (owner) used for running migrations and schema management. For example:
sparky. This user must have CREATEROLE so the application can automatically create the app user on first startup.Password for
SPARKY_FITNESS_DB_USER. Use a strong, randomly generated password. Do not change this after the initial setup — the password is embedded in the database and changing it requires updating the password in PostgreSQL as well.Limited-privilege application database user created automatically by the server on first startup (for example
sparkyapp). Used for all normal application queries with Row Level Security enforced. Can be changed at any time after initialization.Password for
SPARKY_FITNESS_APP_DB_USER. Always required — the server uses this to connect the runtime query pool regardless of whether the user was auto-created or pre-created manually.The public URL of your SparkyFitness frontend. This is used for CORS validation and for constructing links in emails. Examples:
- Local:
http://localhost:3004 - Production:
https://fitness.example.com
A 64-character hexadecimal string used to encrypt sensitive data (API tokens, integration credentials) stored in the database. Generate one with:orNever change this after users have stored integrations — existing encrypted data will become unreadable.
Secret key used by Better Auth to sign session tokens and to encrypt Two-Factor Authentication (2FA / TOTP) data in the database. Generate with:
Mandatory Volume Paths
These variables define host filesystem paths that Docker mounts as persistent volumes. They are mandatory — without them your data will be lost when containers are recreated. Define them in your.env file or directly in docker-compose.yml.
Host path for PostgreSQL data files. Mounted at
/var/lib/postgresql inside the sparkyfitness-db container. Example: ./postgresql or /data/sparkyfitness/db.Host path for server backup files. Mounted at
/app/SparkyFitnessServer/backup inside the sparkyfitness-server container. Example: ./backup.Host path for user-uploaded files (profile pictures, exercise images). Mounted at
/app/SparkyFitnessServer/uploads inside the sparkyfitness-server container. Example: ./uploads.Optional Server Variables
These variables are passed to thesparkyfitness-server service and control backend behaviour. All are optional and have documented defaults.
Set to
true to disable new user self-registration. Existing users can still log in. Useful after initial setup when you want a private instance.Email address of a user who should automatically receive admin privileges on server startup. If not set, no admin user is promoted automatically.
Logging verbosity for the backend server. Accepted values:
DEBUG, INFO, WARN, ERROR. Defaults to INFO.Node.js runtime mode. Set to
production for all deployed instances to enable performance optimisations and tighter security. Defaults to production in Docker images.Server timezone. Use a TZ database name, for example
America/New_York or Etc/UTC. Affects log timestamps and scheduled tasks.Set to
true to hide the email/password login form on the sign-in page. Overridden by SPARKY_FITNESS_FORCE_EMAIL_LOGIN if that is also set.Set to
true to force email/password login to remain enabled regardless of in-app authentication settings. Use this as a fail-safe if you have misconfigured OIDC and need to regain access.Set to
true to allow CORS requests from private network addresses (192.168.x.x, 10.x.x.x, 127.0.0.1, localhost). Defaults to false. Use with caution in production.Comma-separated list of additional URLs that Better Auth should trust. Useful when accessing the app from specific local IPs alongside
ALLOW_PRIVATE_NETWORK_CORS. Example: http://192.168.1.175:8080,http://10.0.0.5:8080.Set to
true to make the Swagger API documentation at /api/api-docs publicly accessible without authentication. Defaults to false.Hostname of the PostgreSQL server. In Docker Compose this defaults to
sparkyfitness-db (the service name). Only change this when using an external database server.PostgreSQL port exposed on the host for external tools (e.g. pgAdmin, DBeaver). Container-to-container communication always uses port
5432 internally. To use this variable you must also uncomment the ports: section under sparkyfitness-db in docker-compose.yml.Email Settings
Configure these variables on thesparkyfitness-server service to enable email notifications (password resets, magic links). If not configured, email functionality is disabled.
SMTP server hostname. Example:
smtp.example.com.SMTP server port. Common values:
587 (STARTTLS), 465 (TLS), 25 (plain).Set to
true to use TLS/SSL for the SMTP connection. Set to false for STARTTLS or plain text.SMTP authentication username (usually your email address).
SMTP authentication password or app-specific password.
The
From: address used for outgoing emails. Example: SparkyFitness <noreply@example.com>.Rate Limiting
API key requests are rate-limited to prevent abuse. These variables are passed to thesparkyfitness-server service.
The time window in milliseconds over which requests are counted. Defaults to
60000 (1 minute).Maximum number of API key requests allowed within the rate-limit window. Defaults to
100.Frontend Variables
These variables are passed to thesparkyfitness-frontend service and configure the Nginx proxy that ships inside the frontend container.
Port on which the internal Nginx server listens. Defaults to
80 when running as root, 8080 when running as non-root. In the production Compose file the container’s port 80 is mapped to host port 3004.Path for the Nginx access log inside the frontend container. Defaults to
/var/log/nginx/access.log when running as root, /dev/stdout when running as non-root.Path for the Nginx error log inside the frontend container. Defaults to
/var/log/nginx/error.log when running as root, /dev/stderr when running as non-root.Set to
true to always dump the complete rendered Nginx configuration to stdout on startup. The configuration is also dumped automatically whenever it is invalid (regardless of this setting). Defaults to false.Internal hostname of the backend server, used by the Nginx proxy inside the frontend container to forward API requests. In Docker Compose this should be
sparkyfitness-server (the service name). Defaults to sparkyfitness-server.Port the backend API server listens on. Used by the Nginx proxy inside the frontend container. Defaults to
3010. Do not change unless you have modified the server configuration.Outbound Proxy
Most deployments do not need these variables. They route the server’s outbound HTTP/HTTPS requests (food provider APIs, fitness integrations, AI providers) through a forward proxy. This is not how you expose SparkyFitness over HTTPS to the internet — for that see the reverse proxy guides.Proxy URL for outbound plain-HTTP requests. Example:
http://proxy.example.com:8888.Proxy URL for outbound HTTPS requests. Usually still an
http:// URL — it names the proxy to tunnel through.Comma-separated list of hostnames and IPs to reach directly, bypassing the proxy. Always include internal Docker service names here (e.g.
localhost,127.0.0.1,sparkyfitness-garmin) to prevent container-to-container calls from being sent to the proxy.Garmin Integration
URL of the Garmin microservice. Must be passed to both
sparkyfitness-server and sparkyfitness-garmin. Example: http://sparkyfitness-garmin:8000. The Garmin service is commented out by default in the production Compose file.Port the Garmin microservice listens on. Must match the port in
GARMIN_MICROSERVICE_URL.Set to
true to connect to Garmin Connect China. Defaults to false.OIDC Configuration
These variables configure an environment-based OpenID Connect (OIDC) provider on thesparkyfitness-server service. When set, an OIDC provider is created or updated at startup and used alongside the existing authentication flow. All SPARKY_FITNESS_OIDC_* variables must be passed through the environment: section of sparkyfitness-server in your docker-compose.yml.
Set to
true to enable OIDC login, overriding the value from the Admin › Authentication Settings panel.Issuer URL of your OIDC provider (e.g.
https://auth.example.com). The discovery document is fetched from <issuer>/.well-known/openid-configuration. Required for the environment provider upsert.Client ID issued by your IdP. Required for the environment provider upsert.
Client secret issued by your IdP. Required for the environment provider upsert.
URL-safe identifier for the provider (e.g.
authentik). Used in login URLs and as a unique key. Required for the environment provider upsert.Human-readable display name shown on the login page (e.g.
Authentik). Optional — defaults to the provider slug.Space-separated OIDC scopes to request. Optional — defaults to
openid email profile.Set to
true to automatically create a new SparkyFitness user account on first OIDC login. Optional — defaults to true.Set to
true to automatically redirect to the single OIDC provider when email/password login is disabled. Optional — defaults to false.URL to a custom logo image displayed on the login button for this provider. Optional.
Organization domain used to restrict access to users from a specific domain. Optional.
Group or claim value from your IdP that maps to the SparkyFitness admin role. Configure your IdP to include this value in token claims. Optional.
Authentication method for the token endpoint. Optional — defaults to
client_secret_post.Algorithm used to sign the ID token. Optional — defaults to
RS256.Algorithm used to sign the UserInfo response. Optional — defaults to
none.Request timeout in milliseconds for OIDC provider communication. Optional — defaults to
30000 (30 seconds).Developer Tools
Set to
true to enable the in-process MCP developer and debugging tools at /mcp: sparky_inspect_schema, sparky_get_user_info, sparky_get_db_stats, and sparky_run_project_tests. Requires an admin API key. These tools run with elevated database access that bypasses Row Level Security. Off by default. Do not enable in production unless you are actively debugging.File-Based Secrets (Docker Swarm / Kubernetes)
For environments that support Docker Secrets or Kubernetes Secrets, two variables can be supplied as file paths instead of plain values:Path to a file containing the API encryption key. When set, takes precedence over
SPARKY_FITNESS_API_ENCRYPTION_KEY. Example: /run/secrets/sparkyfitness_api_key.Path to a file containing the Better Auth secret. When set, takes precedence over
BETTER_AUTH_SECRET. Example: /run/secrets/sparkyfitness_better_auth_secret.Use either the plain variable or the
_FILE variant for each secret — never both. The _FILE approach is preferred in Docker Swarm and Kubernetes deployments where secrets are mounted into containers as files rather than environment variables.