{"id":31628301,"url":"https://github.com/saporus/kumo-mta-ui","last_synced_at":"2026-05-07T05:40:16.251Z","repository":{"id":315619061,"uuid":"1060233190","full_name":"saporus/kumo-mta-ui","owner":"saporus","description":"Modern MailerQ-style admin UI for KumoMTA — with dashboard, queue monitor, logs, API proxy, and one-shot installer.","archived":false,"fork":false,"pushed_at":"2025-09-27T23:06:20.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T23:38:04.213Z","etag":null,"topics":["bulk-email","dashboard","kumomta","kumomta-ui","mail-server","mta","nodejs","opensource","react","ui"],"latest_commit_sha":null,"homepage":"https://www.omniknoweth.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saporus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T15:24:32.000Z","updated_at":"2025-09-27T23:06:24.000Z","dependencies_parsed_at":"2025-09-19T17:51:03.296Z","dependency_job_id":"a7a8dab7-8a41-4e20-82b0-6f44019d38ce","html_url":"https://github.com/saporus/kumo-mta-ui","commit_stats":null,"previous_names":["saporus/kumo-mta-ui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/saporus/kumo-mta-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saporus%2Fkumo-mta-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saporus%2Fkumo-mta-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saporus%2Fkumo-mta-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saporus%2Fkumo-mta-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saporus","download_url":"https://codeload.github.com/saporus/kumo-mta-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saporus%2Fkumo-mta-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278672498,"owners_count":26025925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bulk-email","dashboard","kumomta","kumomta-ui","mail-server","mta","nodejs","opensource","react","ui"],"created_at":"2025-10-06T20:22:18.956Z","updated_at":"2025-10-06T20:22:22.520Z","avatar_url":"https://github.com/saporus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KumoMTA UI (MagicSMTP-style)\n\nA modern, MailerQ-style admin UI for **KumoMTA** with:\n- React + Tailwind frontend (Vite)\n- Secure local **proxy API** (Node/Express) for metrics, policy reload, queue actions, and live logs (SSE)\n- Nginx config and systemd unit for production deploy on AlmaLinux 9\n\n\u003e Assumes **KumoMTA is already installed** and its HTTP listener is bound to `127.0.0.1:8000`.\n\n---\n\n## Features\n\n- **Dashboard:** throughput, queue, recent events, quick actions (Reload Policy, Flush Queue)\n- **Queues:** live view of message queues, showing `Name`, `#Rcpt`, `#KBytes`, `#Conn`, `Paused`, `Mode`, `Last Error`, and `Actions`.  \n  Each row has a **View** button that shows the last 5 errors from the deferred/queue logs.\n- **Logs:** live `journalctl -u kumomta` streaming via Server-Sent Events\n- **API:** documented endpoints behind Nginx, protected by an API key header\n\n---\n\n## Repo Layout\n\n```\nkumo-mta-ui/\n├─ kumo-ui/              # Vite + React + Tailwind (frontend source)\n├─ kumo-ui-api/          # Node/Express proxy (server.js, package.json, .env.example)\n├─ nginx/\n│  └─ kumo-ui.conf       # Nginx site snippet (serves /ui/, proxies /ui/api/)\n├─ systemd/\n│  └─ kumo-ui-api.service# systemd unit for the proxy\n├─ scripts/\n│  └─ install_kumo_ui.sh # One-shot installer (AlmaLinux 9)\n└─ README.md\n```\n\n---\n\n## Quick Start (Dev)\n\n### Prereqs\n- Node.js **18+**\n- KumoMTA HTTP on `http://127.0.0.1:8000` (local only)\n\n### Frontend (dev)\n```bash\ncd kumo-ui\nnpm install\nnpm run dev\n```\n\n### Backend proxy (dev)\n```bash\ncd kumo-ui-api\ncp .env.example .env\n# edit .env: set a long random API_KEY\nnpm install\nnode server.js\n```\n\nThe proxy exposes:\n- `GET  /metrics` → `http://127.0.0.1:8000/metrics.json`\n- `POST /policy/reload` → `systemctl reload kumomta` (default)\n- `POST /queue/flush` → (stub; wire to your workflow)\n- `GET  /logs/stream` → live `journalctl -u kumomta -f -o cat` via SSE\n\n\u003e In production the UI calls `/ui/api/*` through Nginx, which injects `X-API-Key`.\n\n---\n\n## Production Install (AlmaLinux 9)\n\n### 1. Download the project\n\nClone the repo into `/root/`:\n\n```bash\ncd /root\ngit clone https://github.com/saporus/kumo-mta-ui.git\ncd kumo-mta-ui\n```\n\n### 2. Run the one-shot installer\n\n```bash\nsudo bash scripts/install_kumo_ui.sh --domain mail.example.com --api-key \"LONG_RANDOM_SECRET\"\n```\n\nWhat it does:\n1. Installs Node 18, Nginx, tools\n2. Creates service user `kumoapi` + grants journal access  \n   (`usermod -aG systemd-journal kumoapi`)\n3. Copies `kumo-ui-api` → `/opt/kumo-ui-api`, writes `.env`, installs deps\n4. Writes systemd unit running as `kumoapi` with `SupplementaryGroups=systemd-journal`\n5. (Optional) Applies ACLs for `/var/log/kumomta` if present  \n   (`setfacl -Rm u:kumoapi:rx /var/log/kumomta` and default ACL)\n6. Builds the UI → deploys to `/var/www/kumo-ui`\n7. Writes Nginx site for `/ui/` and `/ui/api/` with `X-API-Key` injection\n8. Reloads Nginx and starts the API\n\nOpen: `http://mail.example.com/ui/`\n\n---\n\n## Security Notes\n\n- **Never** expose KumoMTA’s HTTP externally. Bind to `127.0.0.1:8000`.\n- The browser hits `/ui/api/*` → Nginx → local proxy (with `X-API-Key`).\n- Store secrets in `.env` (not committed). Commit only `.env.example`.\n- Consider Basic Auth or JWT in front of the UI for multi-tenant setups (The choice is yours to do).\n\n---\n\n## Build \u0026 Deploy Manually (without installer)\n\n**Proxy**\n```bash\ncd kumo-ui-api\ncp .env.example .env  # set API_KEY and KUMO_HTTP\nnpm install --omit=dev\nsudo cp systemd/kumo-ui-api.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now kumo-ui-api\n```\n\n**UI**\n```bash\ncd kumo-ui\necho \"VITE_API_BASE=/ui/api\" \u003e .env.production\nnpm install\nnpm run build\nsudo mkdir -p /var/www/kumo-ui\nsudo rsync -a dist/ /var/www/kumo-ui/\n```\n\n**Nginx**\n```bash\nsudo cp nginx/kumo-ui.conf /etc/nginx/conf.d/\nsudo sed -i 's/YOUR_HOSTNAME/mail.example.com/' /etc/nginx/conf.d/kumo-ui.conf\nsudo sed -i 's/CHANGE_ME/LONG_RANDOM_SECRET/' /etc/nginx/conf.d/kumo-ui.conf\nsudo nginx -t \u0026\u0026 sudo systemctl reload nginx\n```\n\n---\n\n## API Endpoints (behind Nginx)\n\n- `GET  /ui/api/metrics` → Kumo metrics JSON\n- `POST /ui/api/policy/reload` → reload Kumo policy\n- `POST /ui/api/queue/flush` → (stub) flush queues/maintenance\n- `GET  /ui/api/logs/stream` → SSE live logs\n\nAll calls require header: `X-API-Key: \u003cyour-secret\u003e`\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaporus%2Fkumo-mta-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaporus%2Fkumo-mta-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaporus%2Fkumo-mta-ui/lists"}