Installing Alongside Opterius Panel

Opterius Mail is bundled with the Opterius Panel installer. When you run install.sh on a fresh server, Opterius Mail is automatically cloned, configured, and connected to the Panel. This article describes exactly what the installer does and how to maintain the installation after it is live.

What the Installer Does#

The install.sh script performs the following steps for Opterius Mail (in addition to the Panel itself):

1. Clone the Repository#

git clone https://github.com/opterius/mail /opt/opterius-mail

The application lives at /opt/opterius-mail. This is the deployment path — do not move or rename it after installation.

2. Install PHP Dependencies#

cd /opt/opterius-mail
composer install --no-dev --optimize-autoloader

3. Generate Configuration#

The installer creates /opt/opterius-mail/.env with all required values pre-filled:

APP_NAME="Opterius Mail"
APP_ENV=production
APP_KEY=base64:...           # Generated with php artisan key:generate
APP_DEBUG=false
APP_URL=http://{server-ip}:8090

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=opterius_mail    # Separate DB from the Panel
DB_USERNAME=opterius_mail
DB_PASSWORD={generated}

IMAP_HOST=127.0.0.1          # Local Dovecot
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=false     # Dovecot uses a self-signed cert by default

MAIL_HOST=127.0.0.1          # Local Postfix
MAIL_PORT=587
MAIL_ENCRYPTION=starttls

MAIL_ADMIN=true
MAIL_SYNC_SECRET={generated-32-char-hex}
OPTERIUS_SSO_SECRET={generated-32-char-hex}

4. Create the Database#

The installer creates a dedicated MariaDB database and user:

CREATE DATABASE opterius_mail CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'opterius_mail'@'127.0.0.1' IDENTIFIED BY '{password}';
GRANT ALL PRIVILEGES ON opterius_mail.* TO 'opterius_mail'@'127.0.0.1';

Opterius Mail uses a separate database from the Panel's own database, even though they share the same MariaDB instance.

5. Run Migrations#

php artisan migrate --force

Creates all required tables: admins, mail_domains, mail_accounts, mail_aliases, mail_groups, dkim_keys, autoresponders, user_two_factor, and support tables.

6. Configure Nginx#

The installer creates an Nginx server block for Opterius Mail on port 8090:

server {
    listen 8090;
    server_name _;

    root /opt/opterius-mail/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

7. Set File Permissions#

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

8. Configure Sudoers for Mail Queue#

echo "www-data ALL=(ALL) NOPASSWD: /usr/sbin/postsuper, /usr/sbin/postfix, /usr/bin/mailq" \
    > /etc/sudoers.d/opterius-mail

9. Sync Secrets with the Panel Agent#

The installer writes the same MAIL_SYNC_SECRET and OPTERIUS_SSO_SECRET values to the Panel's agent configuration file so that account sync and SSO work immediately.

After Installation#

Webmail is accessible at:

http://{your-server-ip}:8090

The Panel's Email → Accounts → Open Webmail button uses SSO to log users in directly. The admin panel is at:

http://{your-server-ip}:8090/admin

The first admin account must be created at /admin/setup — see First Admin Setup.

Updating Opterius Mail#

To update to the latest version:

cd /opt/opterius-mail

# Pull latest code
git pull

# Update PHP dependencies
composer install --no-dev --optimize-autoloader

# Apply any new database migrations
php artisan migrate --force

# Clear all caches
php artisan config:clear
php artisan view:clear
php artisan route:clear

# Reload PHP-FPM
sudo systemctl reload php8.2-fpm

Important: Do not run npm run build on the server. The compiled CSS and JavaScript assets are committed to the repository and are updated by git pull. Building on the server is unnecessary and can cause issues if Node.js is not installed.

Reinstalling Opterius Mail (Without Reinstalling the Panel)#

If you need to reinstall Opterius Mail cleanly:

# Remove the existing installation (keeps the database)
rm -rf /opt/opterius-mail

# Clone fresh
git clone https://github.com/opterius/mail /opt/opterius-mail
cd /opt/opterius-mail

composer install --no-dev --optimize-autoloader

# Restore .env from your backup or recreate manually
cp /backups/opterius-mail.env .env

# Run migrations (idempotent — safe if tables already exist)
php artisan migrate --force

# Fix permissions
chown -R www-data:www-data /opt/opterius-mail
chmod -R 775 /opt/opterius-mail/storage

sudo systemctl reload php8.2-fpm

As long as the database is intact and MAIL_SYNC_SECRET / OPTERIUS_SSO_SECRET are preserved in .env, the reinstalled application functions identically to the original.

Firewall Notes#

Port 8090 must be open in your server firewall for users to access webmail:

# UFW
sudo ufw allow 8090/tcp

# firewalld
sudo firewall-cmd --permanent --add-port=8090/tcp && sudo firewall-cmd --reload

On Linode/Akamai Cloud, also open port 8090 in the Linode Cloud Firewall rules in the control panel.