Setup Guide

Install MXCentral, sign in locally, reach webmail, and manage HTTPS without losing changes on upgrade.

MXCentral is package-driven. The hosted installer writes the shared runtime contract, the packages reconcile Apache and service state, the portal uses local-only auth in v1, and SOGo webmail is exposed through the same Apache host as the admin shell.

Portal Passwords API Contracts Use Your Own Certificate

Install and first access

Bootstrap the repo and shared env contract with the hosted installer.
Install mxcentral-release and mxcentral-server from the MXCentral APT repo.
Open the admin shell at https://your-host/.
Open webmail at https://your-host/SOGo/.

Bootstrap and install

wget -qO - https://repo.mxcentral.net/install.sh | sudo bash
sudo apt-get update
sudo apt-get install mxcentral-release mxcentral-server

Package-driven runtime

mxcentral-server now runs runtime reconcile during package configuration.
Normal install and upgrade should not require manual mxcentral-render-config and mxcentral-apply-config calls.

If you intentionally change /etc/mxcentral/mxcentral.env, use:

sudo mxcentral-reconcile-runtime /etc/mxcentral/mxcentral.env

Portal login model

Portal auth is local-only in v1.
Credentials are stored in:
```
/etc/mxcentral/portal/local-users.json
```
Supported roles are global_admin, domain_admin, and mailbox_user.
Mailbox users authenticate with local accounts and can use the MXCentral control panel for mailbox self-service workflows.

Set or rotate a portal password

Use the packaged command instead of editing bcrypt hashes by hand.

Non-interactive

sudo mxcentral-set-portal-password --username admin --password 'replace-this-password'

Interactive prompt

sudo mxcentral-set-portal-password --username admin

The command rewrites password_hash in local-users.json using bcrypt. No Apache restart is required.

Public API contracts

MXCentral publishes the operator-facing API contracts as static OpenAPI artifacts alongside the signed repository.

Runtime and status contract:

https://repo.mxcentral.net/api/openapi/status-v1.yaml

Control-plane public API contract:

https://repo.mxcentral.net/api/openapi/public-api-v1.yaml

Unauthenticated API host status probe:

https://api.app.mxcentral.net/api/v1/status

What the contract covers

Domains, mailboxes, quotas, passwords, domain-admin ACLs, and DKIM workflows.
Quarantine, vacation, sieve, relay profiles, mailing lists, migrations, backups, and support bundles.
Audit events, auth state, mailbox self-service, branding, and recovery surfaces.
The YAML artifacts are versioned in-repo under api/openapi/ and published without requiring portal login.

Create or update a portal user

Use the packaged user-management command to create local admin or mailbox-user entries without editing JSON by hand.

Create or update

sudo mxcentral-manage-portal-user upsert \
  --username ops-admin \
  --display-name "Ops Admin" \
  --role global_admin \
  --password 'replace-this-password'

Domain admin example

sudo mxcentral-manage-portal-user upsert \
  --username domain-admin-2 \
  --display-name "Domain Admin 2" \
  --role domain_admin \
  --password 'replace-this-password' \
  --admin-domains 10,11

List and delete portal users

List

sudo mxcentral-manage-portal-user list

Delete

sudo mxcentral-manage-portal-user delete --username ops-admin

Roles are validated against the v1 local-auth model: global_admin, domain_admin, and mailbox_user.

Reach SOGo webmail

SOGo is exposed through Apache at:
```
https://your-host/SOGo/
```

ActiveSync is exposed at:

https://your-host/Microsoft-Server-ActiveSync/

The portal topbar includes a Webmail link for direct access.

Quick service checks

Verify portal and SOGo

curl -I https://your-host/
curl -I https://your-host/SOGo/
systemctl status apache2 sogo mxcentral-portal --no-pager

Default HTTPS behavior

mxcentral-apache owns the base Apache vhosts and route exposure.
Port 80 redirects to https:// for the same host and path.
Port 443 serves the portal, API, SOGo, and ActiveSync through the MXCentral vhost.
If MXC_TLS_MODE=self-signed, MXCentral creates a self-signed certificate automatically.

The default self-signed certificate paths are:

/etc/apache2/mxcentral/tls/server.crt
/etc/apache2/mxcentral/tls/server.key

Upgrade-safe admin contract

Do not edit package-owned files under /etc/apache2/sites-available/ directly.
Put local Apache customizations in:
```
/etc/apache2/mxcentral-local.d/*.conf
```
MXCentral includes that directory at the end of the HTTPS vhost.
Package upgrades re-render the base vhost but do not remove your local include files.

Use your own certificate

Copy your certificate and key to a stable path on the server.
Set the MXCentral TLS mode to custom.
Point MXCentral at the certificate and key paths in /etc/mxcentral/mxcentral.env.
Reconcile runtime so Apache re-renders and reloads with the new certificate.

Example file placement

sudo mkdir -p /etc/apache2/mxcentral/custom
sudo cp fullchain.pem /etc/apache2/mxcentral/custom/server.crt
sudo cp privkey.pem /etc/apache2/mxcentral/custom/server.key
sudo chmod 0644 /etc/apache2/mxcentral/custom/server.crt
sudo chmod 0600 /etc/apache2/mxcentral/custom/server.key

Required env settings

/etc/mxcentral/mxcentral.env

MXC_TLS_MODE=custom
MXC_TLS_CERT_PATH=/etc/apache2/mxcentral/custom/server.crt
MXC_TLS_KEY_PATH=/etc/apache2/mxcentral/custom/server.key
MXC_TLS_LOCAL_INCLUDE_DIR=/etc/apache2/mxcentral-local.d

Apply the change

sudo mxcentral-reconcile-runtime /etc/mxcentral/mxcentral.env
apachectl configtest
curl -I http://your-host/
curl -I https://your-host/

Local Apache overrides

Use the local include directory for hardening headers, additional redirects, request limits, or server-specific Apache tuning that should survive package upgrades.

Example override

sudo tee /etc/apache2/mxcentral-local.d/hardening.conf >/dev/null <<'EOF'
Header always set X-Frame-Options SAMEORIGIN
Header always set X-Content-Type-Options nosniff
EOF
sudo systemctl reload apache2

Bootstrap defaults

The hosted installer writes these TLS defaults into the shared env file unless you override them:

Default values

MXC_TLS_MODE=self-signed
MXC_TLS_CERT_PATH=/etc/apache2/mxcentral/tls/server.crt
MXC_TLS_KEY_PATH=/etc/apache2/mxcentral/tls/server.key
MXC_TLS_LOCAL_INCLUDE_DIR=/etc/apache2/mxcentral-local.d

Override during bootstrap

wget -qO - https://repo.mxcentral.net/install.sh | sudo bash -s -- \
  --tls-mode custom \
  --tls-cert-path /etc/apache2/mxcentral/custom/server.crt \
  --tls-key-path /etc/apache2/mxcentral/custom/server.key

Setup checklist

Quick checks

curl -I http://your-host/
curl -kI https://your-host/
curl -I https://your-host/SOGo/
systemctl status apache2 sogo mxcentral-portal --no-pager
ls -l /etc/apache2/mxcentral-local.d
apachectl configtest

Expected result: HTTP redirects to HTTPS, HTTPS serves through Apache with either a self-signed or custom certificate, portal passwords are managed with mxcentral-set-portal-password, and SOGo is reachable at /SOGo/.