Everyone

Standalone vs Panel-Integrated Mode

Explains the two deployment modes for Opterius Mail and the differences between them.

Last updated 2026-04-12

Standalone vs Panel-Integrated Mode

Opterius Mail ships as a single codebase that supports two distinct deployment modes. The mode is controlled entirely by settings in your .env file — there is no separate installer or different version to download. Understanding which mode you are in helps you know where to manage accounts, what features are available, and how authentication works.

Mode 1: Standalone

In standalone mode, Opterius Mail operates as a self-contained webmail application connected to any IMAP/SMTP server you configure.

Who uses this: Individuals, small teams, hosting admins who want a modern webmail interface without Opterius Panel, or anyone connecting to an existing mail server (Gmail, Office 365, Dovecot, Exchange, etc.).

How it works:

  • Users log in with their standard IMAP credentials (email + password).
  • Opterius Mail authenticates directly against the IMAP server.
  • There is no account sync — accounts are not pre-created in Opterius Mail's database. An entry in mail_accounts is created the first time a user logs in.
  • The admin panel is optional (MAIL_ADMIN=true enables it), but any admin functions related to account provisioning are limited — the admin can view usage and manage 2FA, but cannot create or delete mail accounts from within Opterius Mail.

A minimal standalone .env looks like:

MAIL_ADMIN=false
MAIL_SYNC_SECRET=          # empty — no Panel sync
OPTERIUS_SSO_SECRET=       # empty — no SSO

Mode 2: Panel-Integrated

In Panel-integrated mode, Opterius Mail is installed and managed by Opterius Panel's installer. The Panel's Go agent keeps the mail_accounts table in sync, and Panel users can access webmail via a single-sign-on link.

Who uses this: Hosting providers and VPS owners running Opterius Panel who want the full managed experience — mail accounts created in Panel automatically appear and work in webmail without any manual configuration.

How it works:

  • When a mail account is created, renamed, or deleted in Opterius Panel, the Panel's Go agent sends a signed webhook to Opterius Mail's sync endpoint.
  • Opterius Mail updates its mail_accounts table accordingly, enabling per-account settings, quotas, and admin visibility before the user ever logs in.
  • Users can click "Open Webmail" in Opterius Panel, which issues a short-lived SSO token so they are logged in automatically without entering credentials again.

A Panel-integrated .env contains:

MAIL_ADMIN=true
MAIL_SYNC_SECRET=a-long-random-secret-shared-with-panel-agent
OPTERIUS_SSO_SECRET=another-long-random-secret-for-sso-tokens

Both secrets are generated automatically by the Opterius Panel installer. You should never need to set these manually unless you are re-installing or recovering.

Feature Comparison

Feature Standalone Panel-Integrated
IMAP authentication Yes Yes
Works with any IMAP server Yes Requires Opterius Panel's Dovecot
Account pre-sync from Panel No Yes (via MAIL_SYNC_SECRET)
SSO from Opterius Panel No Yes (via OPTERIUS_SSO_SECRET)
Admin panel Optional Enabled by default
Admin can see all accounts After first login only Pre-populated from Panel
DKIM signing Configured in SMTP server, not here Panel manages DKIM per domain
Password management Done in mail server admin Done in Opterius Panel
2FA for users Yes (both modes) Yes (both modes)
Custom templates/themes Yes (both modes) Yes (both modes)

Checking Which Mode You Are In

To check the current mode of a running Opterius Mail installation, look at the .env file:

grep -E 'MAIL_SYNC_SECRET|OPTERIUS_SSO_SECRET|MAIL_ADMIN' /opt/opterius-mail/.env

Interpret the output:

Result Mode
MAIL_SYNC_SECRET is empty or absent Standalone
MAIL_SYNC_SECRET has a value Panel-Integrated
MAIL_ADMIN=true Admin panel is enabled (either mode)
OPTERIUS_SSO_SECRET has a value SSO from Panel is active

You can also check the admin panel at http://your-server:8090/admin — if it loads, MAIL_ADMIN=true is set.

Switching Modes

You can switch from standalone to Panel-integrated (or vice versa) at any time by editing .env and restarting the PHP-FPM service:

# Enable Panel-integrated mode
nano /opt/opterius-mail/.env
# Set MAIL_SYNC_SECRET and OPTERIUS_SSO_SECRET to values matching your Panel config

php artisan config:clear && php artisan config:cache
systemctl restart php8.4-fpm

Warning: If you switch to standalone mode from Panel-integrated mode, existing entries in mail_accounts remain in the database but will no longer be synced. Users can still log in via IMAP — they just will not receive automatic account updates from Panel.

When to Choose Each Mode

Choose standalone if:

  • You are not using Opterius Panel.
  • You are evaluating Opterius Mail against an existing mail server.
  • You want webmail for a single domain without a full hosting panel.

Choose Panel-integrated if:

  • You run Opterius Panel and want seamless account management.
  • You want users to access webmail via a one-click link from Panel without re-entering passwords.
  • You want the admin panel to have full visibility into all mail accounts from the moment they are created.
Previous
← First Login