Installation

This guide covers a manual standalone installation of Opterius Mail on a Linux server. If you are installing Opterius Mail as part of Opterius Panel, the Panel installer runs all of these steps automatically — see Standalone vs Panel-Integrated Mode for details.

Before you begin, confirm that your server meets all System Requirements.

1. Clone the Repository#

Install Opterius Mail to /opt/opterius-mail. You can use any path, but this is the conventional location.

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

2. Install PHP Dependencies#

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

Use --no-dev in production to skip development-only packages. The --optimize-autoloader flag generates an optimized class map which improves startup performance.

3. Build Frontend Assets#

npm install
npm run build

This compiles Tailwind CSS 4 and the Alpine.js bundles into public/build/. Node.js is only needed for this step — it does not need to be running at serve time.

4. Configure the Environment File#

Copy the example environment file:

cp .env.example .env

Generate a unique application key:

php artisan key:generate

Open .env in your editor and set these values at minimum:

APP_NAME="Opterius Mail"
APP_ENV=production
APP_DEBUG=false
APP_URL=http://mail.yourdomain.com:8090

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=opterius_mail
DB_USERNAME=omail
DB_PASSWORD=strongpassword

IMAP_HOST=127.0.0.1
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

MAIL_HOST=127.0.0.1
MAIL_PORT=587
MAIL_ENCRYPTION=tls

MAIL_ADMIN=false
MAIL_UI_TEMPLATE=default

See Connecting to Your Mail Server for the full list of IMAP/SMTP options.

5. Run Database Migrations#

php artisan migrate --force

The --force flag is required in APP_ENV=production to acknowledge that migrations will run against a production database.

This creates the following tables: admins, contacts, mail_accounts, user_settings, user_two_factor, and the standard Laravel sessions/cache tables.

6. 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

Replace www-data with your web server user if different (nginx on RHEL-based systems).

7. Configure Nginx#

Opterius Mail runs on port 8090 by default. Create an Nginx server block:

server {
    listen 8090;
    server_name mail.yourdomain.com;

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

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

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

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Save this as /etc/nginx/sites-available/opterius-mail and enable it:

ln -s /etc/nginx/sites-available/opterius-mail /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Optional: Reverse Proxy Behind HTTPS#

If you want to serve Opterius Mail at https://yourdomain.com/webmail instead of on port 8090, add a location block to your existing HTTPS server:

location /webmail {
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

And update APP_URL in .env to https://yourdomain.com/webmail.

8. Configure a Queue Worker (Optional but Recommended)#

Some operations (such as sending large batches or processing sync webhooks from Panel) benefit from a queue worker. Set up a Supervisor process:

[program:opterius-mail-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /opt/opterius-mail/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/opterius-mail-worker.log
stopwaitsecs=3600

supervisorctl reread
supervisorctl update
supervisorctl start opterius-mail-worker:*

9. Open the Firewall#

If users will connect directly to port 8090:

ufw allow 8090/tcp
# or on firewalld:
firewall-cmd --permanent --add-port=8090/tcp
firewall-cmd --reload

10. Verify the Installation#

Open http://your-server:8090 in a browser. You should see the Opterius Mail login page. Try logging in with a valid IMAP email address and password for your mail server.

If you see a Laravel error, check /opt/opterius-mail/storage/logs/laravel.log for details.

Next Steps#

• Configure IMAP and SMTP properly: Connecting to Your Mail Server
• Enable the admin panel: set MAIL_ADMIN=true in .env
• Log in for the first time: First Login