First Admin Setup

After enabling admin mode and running migrations, you need to create the first admin account before you can use the admin panel. This is a one-time process protected by the setup endpoint — once the first admin exists, the setup page is permanently disabled.

Prerequisites#

• MAIL_ADMIN=true is set in .env
• php artisan migrate has been run successfully
• The application is running and reachable at its configured URL

Creating the First Admin#

Step 1 — Navigate to /admin/setup#

Open your browser and go to:

http://your-server:8090/admin/setup

If you see a 404 response, admin mode is not enabled. Go back and follow the Enabling Admin Mode guide.

If you see a login form instead of the setup form, an admin account already exists. Use the login form to sign in, or recover access via the CLI (see below).

Step 2 — Fill in the Setup Form#

The setup form has three fields:

Click Create Admin Account.

Step 3 — Automatic Login and Redirect#

On success, you are automatically logged in as the new admin and redirected to the /admin dashboard. No separate login step is needed after the initial creation.

After the First Admin Is Created#

Once the first admin account exists:

• /admin/setup permanently returns 404 — this is intentional. The setup endpoint cannot be used to create additional admins or to reset existing credentials.
• Additional admin accounts are created from within the admin panel: Admin → Settings → Admins → Add Admin.
• Admin credentials are completely independent of email accounts. An admin user cannot read the emails of mail account holders, and mail account holders cannot log into the admin panel.

Admin vs Webmail Accounts#

This is an important distinction:

If an admin also has a personal email account on the server and wants webmail access, they log in separately at / using their email address and mail password. The admin session and webmail session are entirely independent — having one does not grant the other.

Recovering Access via CLI#

If you are locked out of the admin panel (forgot password, lost 2FA device), you can reset or create an admin account from the command line:

cd /opt/opterius-mail

# Reset an existing admin's password
php artisan mail:admin:password {username} {new-password}

# Create a new admin directly (bypasses the setup page restriction)
php artisan mail:admin:create --name="Backup Admin" --username=backup --password=secret123

These Artisan commands are available in admin mode. If the commands are not found, verify that MAIL_ADMIN=true is set in .env.

Two-Factor Authentication for Admins#

After your first login, it is strongly recommended to enable 2FA for your admin account. Go to Admin → Settings → My Account → Enable 2FA. Admin 2FA is TOTP-based (compatible with any authenticator app). The 2FA secret is stored in the admins table alongside the account record.

Losing access to your 2FA device while it is the only admin account requires CLI recovery (see above).