yakpanel-core/YakPanel-server/README.md

# YakPanel

A web hosting control panel for Linux servers (Ubuntu 22+/Debian, Rocky/Alma 9, EL with `dnf`/`yum`). Built with FastAPI, React, and SQLAlchemy. Descended from YakPanel-style panels, rebuilt with a modern stack.

**YakPanel (yakpanel.com)** treats this repo as the baseline implementation: stack choice, security/privilege model, and distribution strategy are documented in [`../../YakPanel-product/`](../../YakPanel-product/).

## Features

- **Dashboard** - System stats, site/FTP/DB counts
- **Website Management** - Create sites, Nginx vhost, domains, Git deploy (clone/pull)
- **FTP** - FTP account management
- **Databases** - MySQL, PostgreSQL, Redis, MongoDB (create, backup, restore)
- **Files** - File manager (list, read, edit, upload, download, mkdir, rename, delete)
- **Cron** - Scheduled tasks
- **Firewall** - Port rules
- **SSL** - Let's Encrypt certificates via Certbot
- **Docker** - Container list, start, stop, restart
- **Plugins** - Built-in extensions + third-party plugins (add from JSON manifest URL)
- **Backup Plans** - Scheduled site and database backups
- **Users** - Multi-user management (admin only)

## Linux install options (one-click)

All native installs require **root**. Use `sudo -E ...` when you set environment variables so they are preserved.

| Method | When to use |
| --- | --- |
| **curl** | Default; Debian/Ubuntu/RHEL-family with `curl` |
| **wget** | Host has `wget` but not `curl` |
| **Bootstrap `install-curl.sh`** | Same as curl but `YAKPANEL_INSTALLER_BASE` points at your mirror |
| **Local / air-gap** | Tree already on disk: `YAKPANEL_SOURCE_DIR` or `scripts/install.sh` |
| **Docker Compose** | Quick trial / CI; different ports than native (see below) |
| **Web + SSH** | Optional: browser UI at **`/install`** runs the same `install.sh` over **SSH** (off by default; see below) |

### Web-based remote installer (SSH)

**Disabled by default.** Set `ENABLE_REMOTE_INSTALLER=true` in the API environment and restart the backend. Then open the SPA at **`/install`** (e.g. `http://your-panel:8888/install` behind Nginx, or Vite dev with proxy).

- **Security:** The browser sends SSH credentials to your **YakPanel API**; they are **not** stored in the database. Prefer **SSH keys**. **Non-root** users must have **passwordless sudo** (`sudo -n`) because the session is non-interactive. The host running the API must be allowed to reach the **target:SSH port** (and the target must allow **outbound HTTPS** to run `curl` + clone + NodeSource as in `install.sh`).
- **Tuning (env):** `REMOTE_INSTALL_DEFAULT_URL` (HTTPS `install.sh` only), `REMOTE_INSTALL_RATE_LIMIT_PER_IP`, `REMOTE_INSTALL_RATE_WINDOW_MINUTES`, `REMOTE_INSTALL_ALLOWED_TARGET_CIDRS` (comma-separated CIDRs; empty = no restriction), `CORS_EXTRA_ORIGINS` for extra browser origins in production.
- **API:** `GET /api/v1/public-install/config`, `POST /api/v1/public-install/jobs`, WebSocket `/api/v1/public-install/ws/{job_id}` (JSON messages: `line`, `done`).

### Supported distros (native installer)

- **Debian/Ubuntu**: `apt-get` (Nginx `sites-available` layout).
- **RHEL-family** (Rocky, Alma, CentOS Stream, etc.): `dnf` or `yum` (Nginx `conf.d` layout, `firewalld` port if active).

### Environment variables (native `install.sh`)

| Variable | Meaning | Default |
| --- | --- | --- |
| `REPO_URL` | Git URL to clone | `https://source.yakpanel.com/admin/yakpanel-core.git` (override for other mirrors) |
| `YAKPANEL_BRANCH` | Branch/tag for shallow clone | default branch |
| `GIT_REF` | Alias for `YAKPANEL_BRANCH` | — |
| `INSTALL_PATH` | Install directory | `/www/server/YakPanel-server` |
| `PANEL_PORT` | Public HTTP port (Nginx) | `8888` |
| `BACKEND_PORT` | Uvicorn (localhost) | `8889` |
| `YAKPANEL_SOURCE_DIR` | Skip git; path with `backend/` and `frontend/` | unset |

CLI flags: `--repo-url`, `--install-path`, `--branch` / `--ref`, `--source-dir`, `--panel-port`, `--backend-port`, `--help`.

### One-liners (official CDN layout)

Paths assume you publish `install.sh` next to this repo under `…/YakPanel-server/` on your web server.

```bash
curl -fsSL https://www.yakpanel.com/YakPanel-server/install.sh | sudo bash
```

```bash
wget -qO- https://www.yakpanel.com/YakPanel-server/install.sh | sudo bash
```

Mirror / GitHub raw (set your base; no trailing `install.sh`):

```bash
export YAKPANEL_INSTALLER_BASE=https://www.yakpanel.com/YakPanel-server
curl -fsSL "${YAKPANEL_INSTALLER_BASE}/install-curl.sh" | sudo -E bash
```

Custom git mirror and branch:

```bash
curl -fsSL https://www.yakpanel.com/YakPanel-server/install.sh | sudo -E env REPO_URL=https://git.example.com/yakpanel.git YAKPANEL_BRANCH=main bash
```

### Local tree / air-gapped

From the `YakPanel-server` directory (must contain `backend/` and `frontend/`):

```bash
sudo YAKPANEL_SOURCE_DIR="$(pwd)" bash install.sh
```

Or:

```bash
sudo bash scripts/install.sh
```

### Docker (evaluation)

Uses `docker-compose.yml` in this directory — **not** the same layout as native (no host Nginx unit from `install.sh`).

```bash
git clone --depth 1 https://source.yakpanel.com/admin/yakpanel-core.git
# Then cd to this folder (in the full monorepo it is under YakPanel-master/YakPanel-server).
cd YakPanel-master/YakPanel-server
docker compose up -d
```

- **Backend**: `8888` (API on container)
- **Frontend dev server image**: `5173`
- **Redis**: `6379`

For a single compose command without `cd`, set `-f` to your checkout’s `docker-compose.yml`.

**Post-install (all methods):** change the default `admin` password, restrict firewall to SSH + panel port, add TLS (e.g. Let’s Encrypt) for production.

**SELinux (RHEL):** if Nginx returns 403 on static files, fix file contexts or test with permissive mode; see your distro SELinux docs.

## Quick Start (development)

### Backend

```bash
cd YakPanel-server/backend
python -m venv venv
# Windows: venv\Scripts\activate
# Linux: source venv/bin/activate
pip install -r requirements.txt
python scripts/seed_admin.py  # Create admin user (admin/admin)
python run.py
```

### Frontend

```bash
cd YakPanel-server/frontend
npm install
npm run dev
```

- Backend: http://localhost:8888
- Frontend: http://localhost:5173
- Login: admin / admin

## Project Structure

```
YakPanel-server/
├── install.sh        # Canonical native installer
├── install-curl.sh   # Optional: fetch install.sh from YAKPANEL_INSTALLER_BASE
├── backend/          # FastAPI application
│   ├── app/
│   │   ├── api/      # Route handlers
│   │   ├── core/     # Config, security, utils
│   │   ├── models/   # SQLAlchemy models
│   │   ├── services/ # Business logic
│   │   └── tasks/    # Celery tasks
│   └── scripts/      # Seed, etc.
├── frontend/         # React + Vite SPA
├── webserver/        # Nginx vhost templates
├── scripts/          # Delegates to install.sh (local source)
└── docker-compose.yml
```

## Tech Stack

- Backend: FastAPI, SQLAlchemy 2.0, Celery, Redis
- Frontend: React 18, Vite, TypeScript, Tailwind CSS
- Auth: JWT, bcrypt

## License

MIT