Raytha configuration: environment variables reference

Raytha is configured with environment variables. This page lists every variable the 2.0 code reads, with its default, and ends with the settings that live in the database instead.

How configuration is read

The app builds its configuration from the standard ASP.NET Core sources. Later sources win:

appsettings.json (and appsettings.Development.json in Development), shipped with the app.
Process environment variables.
Command-line arguments.

Before any of that, Raytha loads a .env file into the process environment. It looks in the working directory and then in each parent directory. Values in .env replace variables that are already set in the real environment (checked: a .env with PATHBASE beat an exported PATHBASE). With Docker Compose, --env-file .env feeds the variables into the container as usual. Nested keys use a double underscore, which is why the connection string is ConnectionStrings__DefaultConnection.

Values are read when the process starts. Restart the app after you change one.

The tables show the default the code uses when a variable is not set. Where appsettings.json ships a different value, the table says so.

Database

Variable	Default	What it does
`ConnectionStrings__DefaultConnection`	`Host=localhost;Port=5432;Username=postgres;Password=changeme;Database=raytha`	Npgsql connection string. PostgreSQL 17 is the supported database; SQL Server is no longer supported. The repository's Compose file defaults to `Host=db;...`.
`APPLY_PENDING_MIGRATIONS`	`true` in `appsettings.json`, `false` if the key is missing entirely	When `true`, start-up applies pending EF Core migrations and then makes sure the default theme's content exists. Set it to `false` if you run migrations from the SQL scripts in `db/`.
`DATABASE_MAX_SIZE`	`1000000000` (bytes)	The size shown as the limit on the dashboard and maintenance page. It is display-only: Raytha does not stop writes when the database passes it.

Server and runtime

Variable	Default	What it does
`ASPNETCORE_ENVIRONMENT`	`Production`	`Development` turns off HTTPS enforcement and lets the sign-in cookie travel over HTTP. Any other value keeps the cookie `Secure`, redirects HTTP to HTTPS and sends HSTS (unless `ENFORCE_HTTPS=false`).
`ASPNETCORE_URLS`	`http://0.0.0.0:5200`, only when no URL or port setting exists at all	Where Kestrel listens. The Docker image listens on `8080` through the .NET base image's `ASPNETCORE_HTTP_PORTS` setting.
`PATHBASE`	empty	Serve the app under a prefix such as `/mywebsite`. Public-page URLs get the prefix. In 2.0.0 the admin bundle still references `/raytha/...` assets without it, so test the admin before relying on this.
`ENFORCE_HTTPS`	`true`	Outside Development, redirect HTTP to HTTPS and send HSTS. Set `false` when a proxy already enforces HTTPS and you want Raytha to stay out of it. Does nothing in Development.
`REDIRECT_WEBSITE`	empty	A valid absolute URL makes public site requests redirect there. Use it as a maintenance switch.
`NUM_BACKGROUND_WORKERS`	`4`	How many workers pull jobs off the background task queue (CSV imports and other queued jobs). Raytha also runs one scheduler for recurring jobs.

Proxy trust

These control which callers may set X-Forwarded-For and X-Forwarded-Proto. Raytha never honours X-Forwarded-Host. Details and examples are in Running behind a proxy.

Variable	Default	What it does
`TRUSTED_PROXIES`	`all` (also when unset or empty)	`all`, `none`, `private`, or a comma-separated list of IP addresses and CIDR ranges. `all` and `none` must be the only value; `private` can be mixed with addresses and ranges. `private` covers loopback, link-local, RFC 1918, `100.64.0.0/10` and `fc00::/7`. An invalid entry stops start-up.
`TRUSTED_PROXY_HOPS`	`1`	With `all` (or unset), how many proxies sit in front of the app. Setting it together with a list or `none` stops start-up.

Security and limits

Variable	Default	What it does
`ALLOW_INTERNAL_URL_IMPORTS`	`false`	By default, theme and CSV imports, webhook deliveries and HTTP calls made from Raytha Functions refuse to connect to localhost, private networks and cloud metadata addresses. Set `true` to allow them, for example to deliver a webhook to a service on your own network.
`AUTH_RATE_LIMIT_PER_MINUTE`	`30`	Requests per client IP per minute to the sign-in, magic link, forgot-password and setup endpoints. Over the limit, Raytha answers `429` with `Retry-After`. The client IP depends on correct proxy trust.
`IMPERSONATION_MAX_MINUTES`	`60`	Maximum length of an "impersonate this user" session. Values are clamped to 1–1440.

SMTP

See Sending emails for setup and testing.

Variable	Default	What it does
`SMTP_HOST`	empty (`127.0.0.1` in `appsettings.json`)	SMTP server. If it is empty, Raytha reports the system SMTP as missing and uses the SMTP override saved in the admin (Settings, Configuration).
`SMTP_PORT`	`25` in `appsettings.json`	SMTP port. TLS is switched on only for ports `587` and `465`.
`SMTP_USERNAME`, `SMTP_PASSWORD`	empty	Credentials, if the server needs them.
`SMTP_FROM_ADDRESS`, `SMTP_FROM_NAME`	empty	Sender. When set, they win over the defaults saved in the admin.

File storage

See File storage for provider setup.

Variable	Default	What it does
`FILE_STORAGE_PROVIDER`	`Local`	`Local`, `AzureBlob` or `S3` (case-insensitive). Anything else stops start-up.
`FILE_STORAGE_MAX_FILE_SIZE`	`20000000` (bytes)	Largest upload the admin uploader, the Local provider and CSV import accept. Cloud direct uploads go straight to the bucket and are not size-checked by Raytha.
`FILE_STORAGE_MAX_TOTAL_DISK_SPACE`	`1000000000` (bytes)	Display-only storage limit shown on the dashboard.
`FILE_STORAGE_ALLOWED_MIMETYPES`	`text/,image/,video/,audio/,application/pdf`	Comma-separated allow-list. Enforced on the server for every upload path.
`FILE_STORAGE_USE_DIRECT_UPLOAD_TO_CLOUD`	`true`	Browsers upload straight to Azure or S3 using a signed URL. Always off for `Local`.
`FILE_STORAGE_LOCAL_DIRECTORY`	`user-uploads`	Directory for the Local provider, relative to the app's working directory (`/app` in Docker). Files are served from `/_static-files`.
`FILE_STORAGE_AZUREBLOB_CONNECTION_STRING`	empty	Required for Azure Blob.
`FILE_STORAGE_AZUREBLOB_CONTAINER`	empty	Required for Azure Blob.
`FILE_STORAGE_AZUREBLOB_CUSTOM_DOMAIN`	empty	Replaces the storage host in generated URLs, for a CDN or custom domain.
`FILE_STORAGE_S3_ACCESS_KEY`, `FILE_STORAGE_S3_SECRET_KEY`	empty	Required for S3.
`FILE_STORAGE_S3_BUCKET`	empty	Required for S3.
`FILE_STORAGE_S3_SERVICE_URL`	empty	Required for S3, including AWS (for example `https://s3.us-east-1.amazonaws.com`). A non-HTTPS URL only works with direct upload on.
`FILE_STORAGE_S3_REGION`	`us-east-1`	Signing region.

Raytha Functions

Variable	Default	What it does
`RAYTHA_FUNCTIONS_MAX_ACTIVE`	`5`	How many functions may run at the same time. `0` disables Functions.
`RAYTHA_FUNCTIONS_TIMEOUT`	`10000` (ms)	How long one execution may run.
`RAYTHA_FUNCTIONS_QUEUE_TIMEOUT`	`10000` (ms)	How long a call waits for a free slot before it gives up.

Observability

Everything here is off until you set it. When any sink is configured, Serilog replaces the default console logger.

Variable	Default	What it does
`SENTRY_DSN`	empty	Enables Sentry error reporting.
`SENTRY_TRACES_SAMPLE_RATE`	`0`	Fraction of requests traced by Sentry, 0 to 1.
`OTEL_EXPORTER_OTLP_ENDPOINT`	empty	Turns on OpenTelemetry traces and metrics, plus an OTLP log sink.
`OTEL_EXPORTER_OTLP_PROTOCOL`	empty	`grpc`, or anything else for HTTP/protobuf.
`OTEL_SERVICE_NAME`	`raytha`	Service name on exported telemetry.
`OBSERVABILITY_LOGGING_ENABLE_CONSOLE`	`true`	Write logs to the console.
`OBSERVABILITY_LOGGING_ENABLE_LOKI`	`false`	Ship logs to Loki (or a compatible endpoint such as VictoriaLogs). Needs `LOKI_URL`.
`LOKI_URL`, `LOKI_USERNAME`, `LOKI_PASSWORD`	empty	Loki endpoint and optional basic-auth credentials.

Admin app development

Only local development uses these. The Docker image sets AdminSpa__AutoStart=false.

Variable	What it does
`AdminSpa__AutoStart`	Start the Vite dev server together with the app.
`AdminSpa__DevServerUrl`	Where the Vite dev server listens (`http://localhost:5203` in `tools/dev.sh`). Raytha proxies the admin to it.

Settings stored in the database

These are not environment variables. Change them in the admin under Settings.

Configuration: organization name, Website URL, time zone, default sender address and name, and an SMTP override (host, port, username, password).
Authentication: sign-in methods, including JWT and SAML schemes.
Maintenance, Data retention: how many days to keep the audit log, email log, webhook deliveries and finished background tasks. The default is 180 days for each; 0 or less keeps them forever. A background job purges expired rows daily at 03:00 UTC.

Gotchas

The file storage provider is fixed at start-up. Changing FILE_STORAGE_PROVIDER does not move existing files; see File storage.
.env.example and appsettings.json say the S3 service URL is not needed for AWS. The code requires it, and the first upload fails with "S3 Environment Variables were not found" without it.
DATABASE_MAX_SIZE and FILE_STORAGE_MAX_TOTAL_DISK_SPACE do not limit anything. They only change what the dashboard shows.
A password containing ; must be quoted in the connection string, or avoided.
A stray .env in the app's working directory or any parent directory silently overrides real environment variables. If a setting seems to be ignored, look for one.
Keep .env out of version control; it holds your database password and SMTP credentials.

Next steps

Deploy with Docker shows these variables in a working Compose file.
Running behind a proxy for TRUSTED_PROXIES.
File storage and Sending emails.