README.md
Rama main · réplica de lectura del repositorio original.
# MiroTalk Admin
<h1 align="center">MiroTalk Admin - Self-Hosted WebRTC Platform Management & Monitoring</h1>
<h3 align="center">
Open source self-hosted admin dashboard for managing, monitoring, updating, and configuring your MiroTalk WebRTC applications and infrastructure.
</h3>
---
---
## 🚀 Quick Start
1. **Clone the Repository and Set Up Backend**
```bash
git clone https://github.com/miroslavpejic85/mirotalk-admin.git
cd mirotalk-admin
cp backend/config/index.template.js backend/config/index.js
cp .env.template .env
npm install
npm start
```
2. **Open the Admin Dashboard**
- Go to: [http://localhost:9999/admin](http://localhost:9999/admin)
- **Default credentials:**
- **Username:** `mirotalk`
- **Password:** `admin`
---
## ⚡ Quick Start with PM2
1. **Install PM2 globally (if not already installed):**
```bash
npm install -g pm2
```
2. **Clone and set up the project:**
```bash
git clone https://github.com/miroslavpejic85/mirotalk-admin.git
cd mirotalk-admin
cp backend/config/index.template.js backend/config/index.js
cp .env.template .env
npm install
```
3. **Start the server with PM2:**
```bash
pm2 start backend/server.js --name mirotalk-admin
```
4. **View logs and manage the process:**
```bash
pm2 logs mirotalk-admin
pm2 status
```
5. **Access the Dashboard:**
- Open: [http://localhost:9999/admin](http://localhost:9999/admin)
---
## 🐳 Quick Start with Docker
> **Note:** Supports `APP_MANAGE_MODE=ssh` and `APP_MANAGE_MODE=docker`.
> For `docker` mode, uncomment the `/var/run/docker.sock` mount in
> `docker-compose.yml` so the container's bundled Docker CLI can manage
> your sibling MiroTalk containers.
1. **Prepare Your Environment Files**
```bash
git clone https://github.com/miroslavpejic85/mirotalk-admin.git
cd mirotalk-admin
cp backend/config/index.template.js backend/config/index.js
cp .env.template .env
cp docker-compose.template.yml docker-compose.yml
```
2. **Pull and Run with Docker Compose**
```bash
docker pull mirotalk/admin:latest
docker compose up
```
3. **Access the Dashboard**
- Open: [http://localhost:9999/admin](http://localhost:9999/admin)
---
## ⚠️ Security Checklist
> **Important:**
> Before using MiroTalk Admin, update your environment settings to keep your instance secure.
### 🔐 Admin Dashboard
- Set `ADMIN_DASHBOARD_ENABLED=true` to enable the dashboard.
- **Change the default credentials:**
- `ADMIN_USERNAME`
- `ADMIN_PASSWORD_HASH`
👉 generate it by running:
```js
node backend/scripts/hashPassword.js
```
If you install with `sudo ./install.sh`, it auto-generates this value when the template default hash is still present.
The hash contains `$` characters, so keep it wrapped in **single quotes** exactly as printed
(`ADMIN_PASSWORD_HASH='$2b$10$...'`). Do not paste it unquoted into a shell, `pm2` ecosystem file,
systemd unit or `docker-compose.yml`, where `$...` is expanded and the hash gets corrupted.
Restart the admin after editing `.env`.
- `ADMIN_JWT_SECRET`
👉 generate it by running:
```js
node backend/scripts/generateJwtSecret.js
```
If you install with `sudo ./install.sh`, it auto-generates this value when the template default (`supersecret`) is still present.
### 🛠️ Management Mode (`APP_MANAGE_MODE`)
Choose how you want to manage your MiroTalk instance:
- **Local Device Management (via SSH):**
- Set `APP_MANAGE_MODE=ssh`
- Configure:
- `SSH_HOST`
- `SSH_PORT`
- `SSH_USER` (defaults to `root` if unset)
- `SSH_PASSWORD` or `SSH_PRIVATE_KEY_PATH` (absolute path to the private key file)
- `SSH_HOST_FINGERPRINT_SHA256` — **required**. Pinned SHA-256 host-key fingerprint to prevent MITM.
Obtain it with:
```bash
ssh-keyscan -t ed25519 <host> | ssh-keygen -lf - -E sha256
```
Or use the helper script:
```bash
bash backend/scripts/getSshHostFingerprint.sh <host> [port] [key_type]
```
If you install with `sudo ./install.sh` and `APP_MANAGE_MODE=ssh`, the installer tries to auto-generate this value from `SSH_HOST` and `SSH_PORT`.
Paste the resulting `SHA256:…` value (or raw base64 / 64-char hex) into `.env`.
- **Self-Hosted with Docker:**
- Set `APP_MANAGE_MODE=docker`
- **Self-Hosted with PM2:**
- Set `APP_MANAGE_MODE=pm2`
Specify which MiroTalk applications you want to manage by listing their names (comma-separated), and provide the absolute paths to the application and supporting-service directories:
```bash
APP_NAME=mirotalksfu,mirotalk,mirotalkrnd,mirotalkc2c,mirotalkbro,mirotalkwebrtc,callme,mirotalkadmin
MIROTALK_SFU_DIR=/root/mirotalksfu
MIROTALK_P2P_DIR=/root/mirotalk
MIROTALK_RND_DIR=/root/mirotalkrnd
MIROTALK_BRO_DIR=/root/mirotalkbro
MIROTALK_C2C_DIR=/root/mirotalkc2c
MIROTALK_WEB_DIR=/root/mirotalkwebrtc
MIROTALK_CME_DIR=/root/call-me
MIROTALK_ADMIN_DIR=/root/mirotalk-admin
COTURN_DIR=/root/coturn
WHISPER_DIR=/root/whisper
```
> **Running as a non-root user?** The `*_DIR` defaults point to `/root/...`, so set each `*_DIR` to the
> real location of your apps (e.g. `/home/<user>/mirotalksfu`) and set `SSH_USER` to that user.
> The dashboard's **Install / Update / Uninstall** scripts require root (`id -u` must be `0`), and the
> server update/reboot actions use `sudo` (passwordless sudo is needed over SSH).
`COTURN_DIR` and `WHISPER_DIR` configure supporting-service locations and should not be added to `APP_NAME`.
---
> ✅ **Tip:**
> Regularly review and update your `.env` settings to keep your MiroTalk instance secure and manageable.
---
### 🔒 TLS / HTTPS in Production
The dashboard listens on a single HTTPS port (`ADMIN_PORT`) via the
Node.js stdlib `https` module, plaintext HTTP requests on this port are
rejected at the TLS layer and cannot reach the application.
- Defense-in-depth: when `NODE_ENV=production`, any request whose
`req.secure` is false (e.g. arriving through a misconfigured reverse
proxy that did not set `X-Forwarded-Proto: https`) is 301-redirected
to HTTPS for `GET`/`HEAD` and rejected with `403` for any other
method. Plaintext `ws://` socket upgrades are likewise refused.
- The bundled certificate in [backend/ssl/](backend/ssl/) is **self-signed**
and intended for first-boot / local development only. For production,
either:
- replace `backend/ssl/key.pem` and `backend/ssl/cert.pem` with a
certificate issued by a trusted CA (e.g. Let's Encrypt), or
- put the dashboard behind a TLS-terminating reverse proxy
(nginx, Caddy, Traefik, an ALB, etc.) and bind the dashboard to
`127.0.0.1`. When doing so, set `TRUST_PROXY=true` so the
`X-Forwarded-Proto` and `X-Forwarded-For` headers are honored.
- Responses include `Strict-Transport-Security: max-age=63072000; includeSubDomains`
to pin compliant browsers to HTTPS.
#### Local development with a trusted cert
The bundled `backend/ssl/cert.pem` is self-signed, so on the first visit
your browser will show a "Not secure / self-signed certificate" warning.
Click through it once (Chrome: type `thisisunsafe` on the warning page,
or **Advanced → Proceed**; Firefox: **Accept the Risk and Continue**) and
the dashboard at <https://localhost:9999/admin> will load.
To remove the warning entirely in development, install
[`mkcert`](https://github.com/FiloSottile/mkcert) and issue a cert that
your OS / browsers actually trust. Place the dev cert in
`backend/ssl/dev/`, the server auto-detects it when `NODE_ENV` is not
`production` and falls back to `backend/ssl/` otherwise:
<details>
<summary>🍎 macOS</summary>
<br/>
```bash
brew install mkcert nss
mkcert -install
mkdir -p backend/ssl/dev
cd backend/ssl/dev
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
```
</details>
<details>
<summary>🐧 Linux (Debian / Ubuntu)</summary>
<br/>
```bash
sudo apt update
sudo apt install -y libnss3-tools
# install the mkcert binary (pick the latest release for your arch)
curl -fsSLo /tmp/mkcert "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
sudo install -m 0755 /tmp/mkcert /usr/local/bin/mkcert
mkcert -install
mkdir -p backend/ssl/dev
cd backend/ssl/dev
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
```
> On Fedora/RHEL use `sudo dnf install nss-tools`; on Arch use
> `sudo pacman -S nss mkcert`. For Firefox to trust the cert, make sure
> `libnss3-tools` (or `nss-tools`) is installed **before** running
> `mkcert -install`.
</details>
<details>
<summary>🪟 Windows (PowerShell, run as Administrator)</summary>
<br/>
```powershell
# Easiest path: Chocolatey
choco install mkcert
# …or Scoop:
# scoop bucket add extras; scoop install mkcert
mkcert -install
mkdir backend\ssl\dev
cd backend\ssl\dev
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
```
> Firefox on Windows uses its own trust store. After `mkcert -install`,
> restart Firefox so it picks up the new local CA. Chrome / Edge use the
> Windows trust store and work immediately.
</details>
<br/>
`backend/ssl/dev/` is gitignored, so the locally-trusted cert never
ships with the repo. In production the server always uses
`backend/ssl/key.pem` + `backend/ssl/cert.pem`, which should hold a
CA-issued cert (or be replaced by a TLS-terminating reverse proxy as
described above).
Restart the server and the lock icon will be green. The dev workflow is
otherwise unchanged, the dashboard is HTTPS-only in every environment
so behavior in dev matches production (`Secure` cookies, HSTS, mixed
content, `wss://` upgrades, etc.).
---
<p align="center">🌐 Explore the full MiroTalk suite (SFU, P2P, RND, BRO, C2C, WEB, CME, ADM) → <a href="https://docs.mirotalk.com/sites/overview"><strong>MiroTalk Overview</strong></a></p>
---