Environment Variables

Toodle uses environment variables to store configuration values that differ between development and deployment environments.

These values are used to configure services such as the database connection, authentication provider, frontend API address, email delivery, automated reminders, and allowed frontend origin. Sensitive values must never be committed directly to the repository.

Each application repository should provide a .env.example file that lists the required variable names without exposing real credentials or secrets.

Backend Environment Variables

The backend API uses environment variables to configure the server, database connection, authentication provider, email delivery, automated reminders, and allowed frontend origin.

The configuration variables are:

Variable	Purpose
PORT	Port used by the Express API server
NODE_ENV	Identifies the current environment, such as development or production
DATABASE_URL	PostgreSQL connection string used by the backend
AUTH0_DOMAIN	Auth0 tenant domain
AUTH0_AUDIENCE	Identifier for the Toodle API configured in Auth0
AUTH0_CLIENT_ID	Auth0 client identifier used by the application
FRONTEND_URL	Frontend origin allowed to communicate with the API
BREVO_API_KEY	API key used for email delivery
REMINDERS_ENABLED	Enables or disables automated reminders
REMINDERS_INTERVAL_MINUTES	Interval between automated reminder runs

Example structure:

PORT=3000
NODE_ENV=development

DATABASE_URL="postgresql://..."

AUTH0_DOMAIN="your-tenant.auth0.com"
AUTH0_AUDIENCE="https://api.toodle.com"
AUTH0_CLIENT_ID="your-client-id"

FRONTEND_URL="http://localhost:5173"

BREVO_API_KEY="your-brevo-api-key"

REMINDERS_ENABLED=true
REMINDERS_INTERVAL_MINUTES=60

Only example or placeholder values should appear in documentation and .env.example files. Real credentials and secrets must remain outside version control.

Email Delivery and Automated Reminders

Toodle uses Brevo for email delivery and supports automated reminder processing.

Variable	Default	Purpose
REMINDERS_ENABLED	true	Set to false to disable automated reminders. The reminder job does not run when NODE_ENV=test.
REMINDERS_INTERVAL_MINUTES	60	Minutes between reminder runs.

When BREVO_API_KEY is unavailable, emails are recorded as SKIPPED on the relevant notifications, and problem reports return HTTP 503 rather than indicating successful delivery.

This ensures that local or misconfigured environments do not report email deliveries that never occurred.

Frontend Environment Variables

The frontend uses environment variables to identify the backend API and configure authentication.

The configuration variables are:

Variable	Purpose
VITE_API_URL	Base URL used by the frontend when sending requests to the Toodle API
VITE_AUTH0_DOMAIN	Auth0 tenant domain used by the frontend
VITE_AUTH0_CLIENT_ID	Auth0 client identifier for the frontend application
VITE_AUTH0_AUDIENCE	Identifier for the Toodle API in Auth0
VITE_AUTH0_CALLBACK_URL	URL Auth0 redirects the user to after authentication

Example structure:

VITE_API_URL="http://localhost:3000/api/v1"
VITE_AUTH0_DOMAIN="your-tenant.auth0.com"
VITE_AUTH0_CLIENT_ID="your-client-id"
VITE_AUTH0_AUDIENCE="https://api.toodle.com"
VITE_AUTH0_CALLBACK_URL="http://localhost:5173/callback"

Variables prefixed with VITE_ are exposed to the frontend application. Sensitive secrets must never be stored in frontend environment variables.

Creating Your Local .env Files

Each application repository should include a .env.example file that lists the environment variables required by that part of the system.

To create your local configuration:

1. Copy the relevant .env.example file.
2. Rename the copy to .env.
3. Replace the placeholder values with the configuration values provided for your development environment.
4. Keep the .env file local and do not commit it to version control.

For example:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Before starting the application, confirm that all required values have been configured correctly.

Security Guidelines

Environment variables may contain sensitive configuration values and must be handled carefully throughout development.

The team should follow these rules:

• Never commit .env files to Gitea.
• Keep real credentials, API keys, database passwords, and access tokens out of source code and documentation.
• Commit only .env.example files containing variable names and safe placeholder values.
• Use repository or deployment-platform secrets for CI/CD credentials.
• Revoke and replace any secret that is accidentally exposed.
• Do not share sensitive values through public channels or commit history.
• Keep frontend environment variables limited to values that are safe to expose in the browser.

For deployed environments, sensitive configuration should be stored using the secret or environment-variable management tools provided by the hosting platform.

CI/CD Secrets

Some deployment and automation credentials are required by the project's CI/CD workflows. These values must be stored as protected repository secrets rather than committed to source code.

For the documentation deployment workflow, the toodle-docs repository uses the following Gitea Actions secrets:

Secret	Purpose
CLOUDFLARE_API_TOKEN	Authorises the deployment workflow to publish the documentation site to Cloudflare Pages
CLOUDFLARE_ACCOUNT_ID	Identifies the Cloudflare account used for the deployment

These secrets are referenced by the Gitea Actions workflow during deployment but are not stored directly in the workflow file.

As additional deployment services are configured, any sensitive credentials required by CI/CD should follow the same approach.

Documentation Environment

The toodle-docs repository does not require a standard .env file for normal local development.

To run the documentation locally, install the required Python dependencies and start the MkDocs development server:

pip install -r requirements.txt
mkdocs serve

Deployment credentials used by the documentation pipeline are stored securely as Gitea Actions secrets and are not required for simply previewing or editing the documentation locally.