CodeWithCJ · CodeWithCJ · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026
diff --git a/docs/content/0.index.md b/docs/content/0.index.md
@@ -3,6 +3,10 @@
 
 Welcome to the comprehensive documentation for **SparkyFitness**, a self-hosted alternative to MyFitnessPal with AI-powered nutrition assistance.
 
+:::info
+**Disclaimer**: While we strive to keep this documentation as accurate and up-to-date as possible, some sections may occasionally become outdated. If you encounter any issues or have questions, please reach out via our [GitHub Discussions](https://github.com/CodeWithCJ/SparkyFitness/discussions) or join our [Discord community](https://discord.gg/vcnMT5cPEA) where others can help you.
+:::
+
 ## What is SparkyFitness?
 
 SparkyFitness is a full-stack fitness tracking application that helps you monitor nutrition, exercise, body measurements, and achieve your health goals. Built with modern web technologies and designed for self-hosting, it provides complete control over your fitness data.

diff --git a/docs/content/1.install/6.environment-variables.md b/docs/content/1.install/6.environment-variables.md
@@ -5,20 +5,29 @@ This document provides a comprehensive list and detailed descriptions of all env
 For a complete list of all available variables and their detailed descriptions, please refer to the example environment file:
 [`.env.example` on GitHub](https://github.com/CodeWithCJ/SparkyFitness/blob/main/docker/.env.example)
 
+:::warning
+**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 intial setup. If you need to change, you will need to update the password in the database and udpate the env variable.
+- **`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` 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.
-- **`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` or `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`.
-  - **Note**: If this variable is not set, the server will **automatically generate** a temporary secret on startup to allow the application to run. However, this means that **all user sessions will be invalidated** whenever the server restarts. For a stable production environment, you **must** explicitly set this variable to a persistent value.
+- **`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'))"`
+  - **Note**: If this variable is not set, the server will **automatically generate** a temporary secret on startup. However, this means that **all user sessions will be invalidated** whenever the server restarts. For a stable production environment, you **must** explicitly set this variable to a persistent value.
 
 ## Mandatory Volume Paths
 
@@ -30,50 +39,74 @@ These paths define where Docker volumes will store persistent data on your host.
 
 ## Optional Configuration
 
-- **`SPARKY_FITNESS_DB_HOST`**: The hostname of the PostgreSQL database. For Docker Compose, this defaults to `sparkyfitness-db` (the service name for inter-container communication). 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, DBeaver). To use this, you must also uncomment the `ports` section under `sparkyfitness-db` in `docker-compose.prod.yml`. **Important:** Inside Docker, containers always communicate on port `5432` (the internal PostgreSQL port). Changing this value will **not** affect container-to-container communication. The server's internal `SPARKY_FITNESS_DB_PORT` is hardcoded to `5432` in the Docker Compose file. If you are using external database server, you can change this value to match your external database server port.
-- **`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.
+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.
-- **OIDC (env-configured provider)**  
-  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`). 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.
 
-- **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.
-
-- **API Key Rate Limiting**: API keys (used by automation tools like n8n or the mobile app) are rate-limited to prevent abuse. The defaults are suitable for most use cases.
-  - **`SPARKY_FITNESS_API_KEY_RATELIMIT_WINDOW_MS`**: The time window in milliseconds for the rate limit counter. Defaults to `60000` (1 minute).
-  - **`SPARKY_FITNESS_API_KEY_RATELIMIT_MAX_REQUESTS`**: The maximum number of requests allowed per time window. Defaults to `100`.
-
-- **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`.
+### 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`.