Complete reference table of all .env configuration variables for Opterius Mail, organised by section.
Environment Variables Reference
All Opterius Mail configuration is driven by the .env file at /opt/opterius-mail/.env. After editing .env, run php artisan config:clear to apply the changes.
App Settings#
| Variable |
Default |
Required |
Description |
APP_NAME |
Opterius Mail |
No |
Application display name shown in the browser title and emails. |
APP_ENV |
production |
Yes |
Environment mode. production enables caching and disables debug output. Use local for development. |
APP_KEY |
(none) |
Yes |
32-byte base64 Laravel encryption key. Generate with php artisan key:generate. Never share or commit this value. |
APP_DEBUG |
false |
No |
Set true to show full exception stack traces. Never enable in production — exposes server internals. |
APP_URL |
http://localhost:8090 |
Yes |
The public URL of the application including port. Used for generating links in emails and SSO redirects. |
LOG_CHANNEL |
stack |
No |
Laravel logging channel. Use stack (combined) or single (one file). |
LOG_LEVEL |
error |
No |
Minimum log severity. Options: debug, info, notice, warning, error, critical. Set debug for troubleshooting. |
Database#
| Variable |
Default |
Required |
Description |
DB_CONNECTION |
mysql |
Yes |
Database driver. Options: mysql (MariaDB/MySQL), sqlite (development only), pgsql. |
DB_HOST |
127.0.0.1 |
Yes |
Database server hostname or IP. |
DB_PORT |
3306 |
No |
Database port. Default: 3306 (MySQL/MariaDB), 5432 (PostgreSQL). |
DB_DATABASE |
opterius_mail |
Yes |
Database name. |
DB_USERNAME |
opterius_mail |
Yes |
Database user. |
DB_PASSWORD |
(none) |
Yes |
Database password. |
IMAP (Incoming Mail)#
| Variable |
Default |
Required |
Description |
IMAP_HOST |
127.0.0.1 |
Yes |
IMAP server hostname. Use 127.0.0.1 for local Dovecot; use the remote hostname for external mail servers. |
IMAP_PORT |
993 |
No |
IMAP port. Standard ports: 993 (SSL/TLS), 143 (STARTTLS or plaintext). |
IMAP_ENCRYPTION |
ssl |
No |
Encryption method. Options: ssl (IMAPS, wraps connection immediately), tls (STARTTLS, upgrades after connect), none (plaintext — not recommended in production). |
IMAP_VALIDATE_CERT |
false |
No |
Whether to validate the IMAP server's TLS certificate. Set false when using a self-signed certificate (standard for local Dovecot). Set true for remote servers with valid certificates. |
IMAP_USERNAME_SUFFIX |
(none) |
No |
String appended to the username when authenticating with IMAP. For example, if your Dovecot requires user@domain format but users enter only user, set this to @yourdomain.com. Leave empty when users log in with full email addresses. |
SMTP (Outgoing Mail)#
| Variable |
Default |
Required |
Description |
MAIL_HOST |
127.0.0.1 |
Yes |
SMTP relay server hostname. Use 127.0.0.1 for local Postfix. |
MAIL_PORT |
587 |
No |
SMTP port. Standard ports: 587 (STARTTLS submission — recommended), 465 (SMTPS), 25 (unencrypted). |
MAIL_USERNAME |
(none) |
No |
SMTP authentication username. Not required when relaying through a local Postfix that does not require SMTP auth for localhost connections. |
MAIL_PASSWORD |
(none) |
No |
SMTP authentication password. |
MAIL_ENCRYPTION |
tls |
No |
SMTP encryption. Options: tls (STARTTLS), ssl (SMTPS), none. |
MAIL_FROM_ADDRESS |
(none) |
No |
Default From address for system-generated emails (password reset notifications, admin alerts). Normally set to noreply@yourdomain.com. |
MAIL_FROM_NAME |
Opterius Mail |
No |
Display name for system-generated emails. |
Admin Mode#
| Variable |
Default |
Required |
Description |
MAIL_ADMIN |
false |
No |
Set true to enable the admin panel at /admin and the account sync API at /api/sync/account. Requires running php artisan migrate after enabling. |
DOVECOT_PASSWORD_SCHEME |
BLF-CRYPT |
No |
Password hashing format used when storing account passwords. Options: BLF-CRYPT (bcrypt, default), SHA512-CRYPT. Must match your Dovecot passdb query. |
UI / Template#
| Variable |
Default |
Required |
Description |
MAIL_UI_TEMPLATE |
default |
No |
Active webmail UI template name. Must match a directory in resources/views/templates/. Falls back to default if the named directory does not exist. |
Panel Integration#
| Variable |
Default |
Required |
Description |
MAIL_SYNC_SECRET |
(none) |
No |
32-character hex shared secret for the Panel account sync API (POST /api/sync/account). When not set, the sync endpoint returns 404 (standalone mode). Must match the value in the Panel agent config. |
OPTERIUS_SSO_SECRET |
(none) |
No |
32-character hex shared secret for SSO JWT token validation. When not set, the /sso/login route returns 404. Must match the value in the Opterius Panel config. |
Spam Filtering#
| Variable |
Default |
Required |
Description |
RSPAMD_URL |
(none) |
No |
Full URL of the Rspamd HTTP controller API, e.g. http://127.0.0.1:11334. When not set, the Admin → Spam section is hidden and Rspamd integration is disabled. |
RSPAMD_PASSWORD |
(none) |
No |
Rspamd controller password. Required if Rspamd is configured with enable_password or password. Leave empty if Rspamd is restricted to localhost without a password. |
Cache and Session#
| Variable |
Default |
Required |
Description |
CACHE_DRIVER |
file |
No |
Cache backend. Options: file (default, no extra setup), redis (recommended for production with multiple users), database, array (in-memory, lost on restart). |
SESSION_DRIVER |
file |
No |
Session backend. Same options as CACHE_DRIVER. Use redis for sticky sessions across multiple PHP-FPM workers. |
SESSION_LIFETIME |
120 |
No |
Session timeout in minutes. After this period of inactivity, the user is logged out. |
Queue#
| Variable |
Default |
Required |
Description |
QUEUE_CONNECTION |
sync |
No |
Queue driver. sync runs jobs immediately inline (no worker needed, fine for most deployments). database or redis enables background processing — requires a running php artisan queue:work process. |
Redis (When Used)#
| Variable |
Default |
Required |
Description |
REDIS_HOST |
127.0.0.1 |
No |
Redis server hostname. |
REDIS_PORT |
6379 |
No |
Redis port. |
REDIS_PASSWORD |
(none) |
No |
Redis authentication password. Leave empty if Redis is on localhost without auth. |
REDIS_DB |
0 |
No |
Redis database index for cache. |
REDIS_CACHE_DB |
1 |
No |
Separate Redis database index for application cache. |