https://github.com/saporus/kumo-mta-ui
Modern MailerQ-style admin UI for KumoMTA — with dashboard, queue monitor, logs, API proxy, and one-shot installer.
https://github.com/saporus/kumo-mta-ui
bulk-email dashboard kumomta kumomta-ui mail-server mta nodejs opensource react ui
Last synced: about 1 month ago
JSON representation
Modern MailerQ-style admin UI for KumoMTA — with dashboard, queue monitor, logs, API proxy, and one-shot installer.
- Host: GitHub
- URL: https://github.com/saporus/kumo-mta-ui
- Owner: saporus
- License: mit
- Created: 2025-09-19T15:24:32.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-27T23:06:20.000Z (9 months ago)
- Last Synced: 2025-09-27T23:38:04.213Z (9 months ago)
- Topics: bulk-email, dashboard, kumomta, kumomta-ui, mail-server, mta, nodejs, opensource, react, ui
- Language: TypeScript
- Homepage: https://www.omniknoweth.com
- Size: 69.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# KumoMTA UI (MagicSMTP-style)
A modern, MailerQ-style admin UI for **KumoMTA** with:
- React + Tailwind frontend (Vite)
- Secure local **proxy API** (Node/Express) for metrics, policy reload, queue actions, and live logs (SSE)
- Nginx config and systemd unit for production deploy on AlmaLinux 9
> Assumes **KumoMTA is already installed** and its HTTP listener is bound to `127.0.0.1:8000`.
---
## Features
- **Dashboard:** throughput, queue, recent events, quick actions (Reload Policy, Flush Queue)
- **Queues:** live view of message queues, showing `Name`, `#Rcpt`, `#KBytes`, `#Conn`, `Paused`, `Mode`, `Last Error`, and `Actions`.
Each row has a **View** button that shows the last 5 errors from the deferred/queue logs.
- **Logs:** live `journalctl -u kumomta` streaming via Server-Sent Events
- **API:** documented endpoints behind Nginx, protected by an API key header
---
## Repo Layout
```
kumo-mta-ui/
├─ kumo-ui/ # Vite + React + Tailwind (frontend source)
├─ kumo-ui-api/ # Node/Express proxy (server.js, package.json, .env.example)
├─ nginx/
│ └─ kumo-ui.conf # Nginx site snippet (serves /ui/, proxies /ui/api/)
├─ systemd/
│ └─ kumo-ui-api.service# systemd unit for the proxy
├─ scripts/
│ └─ install_kumo_ui.sh # One-shot installer (AlmaLinux 9)
└─ README.md
```
---
## Quick Start (Dev)
### Prereqs
- Node.js **18+**
- KumoMTA HTTP on `http://127.0.0.1:8000` (local only)
### Frontend (dev)
```bash
cd kumo-ui
npm install
npm run dev
```
### Backend proxy (dev)
```bash
cd kumo-ui-api
cp .env.example .env
# edit .env: set a long random API_KEY
npm install
node server.js
```
The proxy exposes:
- `GET /metrics` → `http://127.0.0.1:8000/metrics.json`
- `POST /policy/reload` → `systemctl reload kumomta` (default)
- `POST /queue/flush` → (stub; wire to your workflow)
- `GET /logs/stream` → live `journalctl -u kumomta -f -o cat` via SSE
> In production the UI calls `/ui/api/*` through Nginx, which injects `X-API-Key`.
---
## Production Install (AlmaLinux 9)
### 1. Download the project
Clone the repo into `/root/`:
```bash
cd /root
git clone https://github.com/saporus/kumo-mta-ui.git
cd kumo-mta-ui
```
### 2. Run the one-shot installer
```bash
sudo bash scripts/install_kumo_ui.sh --domain mail.example.com --api-key "LONG_RANDOM_SECRET"
```
What it does:
1. Installs Node 18, Nginx, tools
2. Creates service user `kumoapi` + grants journal access
(`usermod -aG systemd-journal kumoapi`)
3. Copies `kumo-ui-api` → `/opt/kumo-ui-api`, writes `.env`, installs deps
4. Writes systemd unit running as `kumoapi` with `SupplementaryGroups=systemd-journal`
5. (Optional) Applies ACLs for `/var/log/kumomta` if present
(`setfacl -Rm u:kumoapi:rx /var/log/kumomta` and default ACL)
6. Builds the UI → deploys to `/var/www/kumo-ui`
7. Writes Nginx site for `/ui/` and `/ui/api/` with `X-API-Key` injection
8. Reloads Nginx and starts the API
Open: `http://mail.example.com/ui/`
---
## Security Notes
- **Never** expose KumoMTA’s HTTP externally. Bind to `127.0.0.1:8000`.
- The browser hits `/ui/api/*` → Nginx → local proxy (with `X-API-Key`).
- Store secrets in `.env` (not committed). Commit only `.env.example`.
- Consider Basic Auth or JWT in front of the UI for multi-tenant setups (The choice is yours to do).
---
## Build & Deploy Manually (without installer)
**Proxy**
```bash
cd kumo-ui-api
cp .env.example .env # set API_KEY and KUMO_HTTP
npm install --omit=dev
sudo cp systemd/kumo-ui-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kumo-ui-api
```
**UI**
```bash
cd kumo-ui
echo "VITE_API_BASE=/ui/api" > .env.production
npm install
npm run build
sudo mkdir -p /var/www/kumo-ui
sudo rsync -a dist/ /var/www/kumo-ui/
```
**Nginx**
```bash
sudo cp nginx/kumo-ui.conf /etc/nginx/conf.d/
sudo sed -i 's/YOUR_HOSTNAME/mail.example.com/' /etc/nginx/conf.d/kumo-ui.conf
sudo sed -i 's/CHANGE_ME/LONG_RANDOM_SECRET/' /etc/nginx/conf.d/kumo-ui.conf
sudo nginx -t && sudo systemctl reload nginx
```
---
## API Endpoints (behind Nginx)
- `GET /ui/api/metrics` → Kumo metrics JSON
- `POST /ui/api/policy/reload` → reload Kumo policy
- `POST /ui/api/queue/flush` → (stub) flush queues/maintenance
- `GET /ui/api/logs/stream` → SSE live logs
All calls require header: `X-API-Key: `
---
## License
MIT