Environment variables reference

Konversio is configured through environment variables, typically defined in a .env file at the project root. The repository ships a .env.example with the full list and inline comments — treat that file as the authoritative reference. This article covers the variables you must set or are most likely to need to change.

Required variables

These must be set before the app will start correctly.

SECRET_KEY_BASE
A long random string used to sign session cookies and encrypted tokens. Generate one with openssl rand -hex 64. Never reuse across environments, never commit to version control.

FRONTEND_URL
The public URL of your Konversio instance, e.g. https://support.example.com. Used in email templates, widget embed snippets, and webhook callbacks. Must match your actual domain — mismatches break email links and live chat.

RAILS_ENV
Set to production for any real deployment. The default in development is development, which disables caching and enables verbose logging.

Email (SMTP)

All four of these are required for outbound email to work.

Variable	Example
`SMTP_ADDRESS`	`smtp.eu.mailprovider.com`
`SMTP_PORT`	`587`
`SMTP_USERNAME`	`your@email.com`
`SMTP_PASSWORD`	`yourpassword`

Optional email variables:

SMTP_DOMAIN — your sending domain, used in HELO
SMTP_AUTHENTICATION — defaults to plain; use login or cram_md5 if required
SMTP_ENABLE_STARTTLS_AUTO — defaults to true
MAILER_SENDER_EMAIL — the From address on system emails

Storage

ACTIVE_STORAGE_SERVICE
Controls where file attachments are stored. Two options:

local (default) — files stored on disk at storage/ inside the container volume
amazon — use any S3-compatible endpoint (works with Scaleway Object Storage, Hetzner, Backblaze B2, etc.)

When using S3-compatible storage, also set:

S3_BUCKET_NAME=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
S3_ENDPOINT_URL=   # required for non-AWS providers

Internationalisation

DEFAULT_LOCALE
Sets the default UI language. Defaults to en. Supported locales are listed in config/locales/.

Pilot AI variables

Pilot replaces Chatwoot's proprietary Captain AI. Instead of being locked to a single vendor, Pilot is configured by pointing it at any OpenAI-compatible API endpoint.

Variable	Purpose
`PILOT_ENABLED`	Set to `true` to activate Pilot
`PILOT_AI_PROVIDER_URL`	API base URL (e.g. Mistral, Ollama, Scaleway AI)
`PILOT_AI_API_KEY`	API key for the provider (leave blank for local Ollama)
`PILOT_AI_MODEL`	Model name, e.g. `mistral-small-latest`, `gemma3:4b`

These are optional in the sense that Konversio runs without them — Pilot simply stays inactive.

Optional but commonly needed

LOG_LEVEL — info in production; debug when troubleshooting
FORCE_SSL — set to true behind a TLS-terminating reverse proxy
DISABLE_TELEMETRY — set to true to prevent any outbound telemetry pings
WEB_CONCURRENCY — number of Puma workers; defaults to 2, raise for more throughput

For the complete list with descriptions, see .env.example in the repository root.