System Requirements

This page covers everything your server needs before you install Opterius Mail. If you are installing Opterius Mail as part of Opterius Panel, the Panel installer handles the mail stack for you — skip to Panel Integration instead. These requirements apply to standalone installations.

PHP#

Install PHP and extensions on Ubuntu/Debian:

apt install php8.4 php8.4-fpm php8.4-imap php8.4-mbstring php8.4-xml \
    php8.4-curl php8.4-zip php8.4-pdo php8.4-mysql php8.4-gd

On AlmaLinux/RHEL:

dnf install php84 php84-php-fpm php84-php-imap php84-php-mbstring php84-php-xml \
    php84-php-curl php84-php-zip php84-php-pdo php84-php-mysqlnd php84-php-gd

Database#

For production, use MySQL 8.0+ or MariaDB 10.6+. SQLite is supported for local development only — do not use SQLite in a multi-user production environment.

Create a dedicated database and user before running migrations:

CREATE DATABASE opterius_mail CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'omail'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON opterius_mail.* TO 'omail'@'localhost';
FLUSH PRIVILEGES;

Composer#

Composer 2.x is required. Composer 1.x will not work with Laravel 12 dependencies.

composer --version
# Composer version 2.x.x

If Composer is not installed:

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

Node.js and npm#

Node.js 20 LTS or newer is required to build the CSS and JavaScript assets. This step is done during installation or when upgrading; Node.js does not need to be running at serve time.

node --version   # v20.x.x or higher
npm --version    # 10.x.x or higher

Install via NodeSource on Ubuntu:

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install nodejs

Note for Opterius Panel users: Opterius Panel's installer already ensures Node.js is present. If you are on a Panel server you likely already meet this requirement.

Mail Server#

Opterius Mail is a webmail front-end — it does not deliver or receive email itself. You need a working mail server:

Opterius Mail connects to your IMAP server as each user using their credentials. It does not require a service account or admin IMAP access.

Dovecot Checklist#

• IMAP service must be listening (default port 993 for SSL, or 143 for STARTTLS).
• SSL certificate must be valid, or IMAP_VALIDATE_CERT=false must be set for self-signed certs.
• auth_mechanisms = plain login must be enabled in Dovecot.

Postfix Checklist#

• SMTP submission must be available (port 587 with STARTTLS recommended, or port 465 SMTPS).
• smtpd_sasl_auth_enable = yes for authenticated submission.

Network & Ports#

Port 8090 must be open in your firewall if users access Opterius Mail directly. If you place Nginx or Apache in front as a reverse proxy on port 80/443, only the proxy port needs to be externally accessible.

File & Directory Permissions#

The web server user (typically www-data on Debian/Ubuntu, nginx or apache on RHEL) must be able to read and write these paths:

storage/          → writable (logs, cache, sessions, uploads)
bootstrap/cache/  → writable (framework cache)
public/           → readable

chown -R www-data:www-data /opt/opterius-mail
chmod -R 755 /opt/opterius-mail
chmod -R 775 /opt/opterius-mail/storage
chmod -R 775 /opt/opterius-mail/bootstrap/cache

When Running with Opterius Panel#

When Opterius Mail is installed by Opterius Panel's installer, the following are already satisfied automatically:

• PHP 8.4 with all required extensions (installed by Panel)
• MySQL 8.0 (already running for Panel)
• Dovecot + Postfix (already configured by Panel)
• Node.js (already installed by Panel)

The installer creates a separate opterius_mail database and configures .env for you, including MAIL_SYNC_SECRET for account sync.