203 lines
6.2 KiB
Markdown
203 lines
6.2 KiB
Markdown
# Server Panel
|
|
|
|
Server Panel is an MVP foundation for a web-based server management interface with future Telegram bot integration.
|
|
|
|
## What Is Included
|
|
|
|
- FastAPI backend scaffold
|
|
- React + Vite frontend scaffold
|
|
- Telegram bot process scaffold
|
|
- Docker Compose foundation for local development
|
|
- project documentation in `docs/`
|
|
|
|
## Recommended Host Control Model
|
|
|
|
By default, containers do not have the ability to safely manage the host machine directly.
|
|
|
|
This project starts with a safer assumption:
|
|
|
|
- UI, API, and bot may run in containers;
|
|
- control actions should go through an explicit integration layer;
|
|
- the default integration mode is `ssh`.
|
|
|
|
For the MVP, the recommended approach is:
|
|
|
|
1. Run the panel components in containers.
|
|
2. Let the backend or worker connect to target servers over SSH.
|
|
3. Restrict actions to a whitelist such as service status, start, stop, restart, and recent logs.
|
|
4. Record every control action in audit logs.
|
|
|
|
For the current backend slice:
|
|
|
|
- server reachability uses a TCP connectivity check;
|
|
- metrics collection uses SSH;
|
|
- SSH metrics require `ssh_username` on the server record;
|
|
- the application can use a private key path from `SSH_PRIVATE_KEY_PATH`;
|
|
- service control uses predefined SSH commands only;
|
|
- action persistence and audit logging are enabled;
|
|
- actions are queued in the API and executed by the worker process by default;
|
|
- logs are available for managed services through `journalctl`, `docker logs`, or `file:/absolute/path`.
|
|
- browser access can be limited through `CORS_ALLOWED_ORIGINS`.
|
|
|
|
## Confirmed MVP Scope
|
|
|
|
The current MVP is intentionally constrained to keep operations predictable and reviewable.
|
|
|
|
Target environment:
|
|
|
|
- Linux target hosts only for the first release;
|
|
- SSH is the supported control path for those hosts;
|
|
- `docker_api` and `agent` remain reserved for later expansion.
|
|
|
|
Managed service scope:
|
|
|
|
- only explicitly registered managed services may be controlled from the panel;
|
|
- supported managed service types are `systemd` and `docker`;
|
|
- allowed actions are `status`, `start`, `stop`, `restart`, and recent logs;
|
|
- free-form shell commands are out of scope for the MVP.
|
|
|
|
## Why Not Let the Container Control the Host Directly
|
|
|
|
It is technically possible, but usually not a good default.
|
|
|
|
Examples of direct host access patterns:
|
|
|
|
- mounting `/var/run/docker.sock`
|
|
- using `privileged` containers
|
|
- sharing host PID namespace
|
|
- mounting host filesystems
|
|
- talking to host `systemd` directly
|
|
|
|
These approaches can effectively grant root-equivalent access and significantly increase risk.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
backend/ FastAPI app
|
|
frontend/ React + Vite app
|
|
bot/ Telegram bot process
|
|
docs/ Project documentation
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. Copy `.env.example` to `.env`
|
|
2. Review secrets, `VITE_API_BASE_URL`, and `CORS_ALLOWED_ORIGINS`
|
|
3. Start services:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
4. Open:
|
|
|
|
- backend: `http://localhost:8000/health`
|
|
- frontend: `http://localhost:5173`
|
|
|
|
## Production Deployment
|
|
|
|
Production-oriented files now included:
|
|
|
|
- `.env.production.example`
|
|
- `docker-compose.prod.yml`
|
|
- `deploy/nginx/server-panel.conf`
|
|
- `docs/deployment.md`
|
|
- `docs/rollback.md`
|
|
|
|
Recommended production flow:
|
|
|
|
1. Copy `.env.production.example` to `.env.production`
|
|
2. Replace placeholder secrets and origin values
|
|
3. Keep `FRONTEND_PUBLIC_API_BASE_URL=/api/v1` unless the public API path differs
|
|
4. Start the stack:
|
|
|
|
```bash
|
|
docker compose --env-file .env.production -f docker-compose.prod.yml up --build -d
|
|
```
|
|
|
|
4. Verify:
|
|
|
|
- `http://YOUR_HOST/health`
|
|
- `http://YOUR_HOST/`
|
|
|
|
Rollback steps are documented in `docs/rollback.md`.
|
|
|
|
## First Admin Bootstrap
|
|
|
|
After the backend starts, create the first administrator once:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/auth/bootstrap \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username":"admin","password":"strong-pass-123"}'
|
|
```
|
|
|
|
After that, use:
|
|
|
|
- `POST /api/v1/auth/login`
|
|
- `GET /api/v1/auth/me`
|
|
- `GET /api/v1/servers`
|
|
- `POST /api/v1/servers`
|
|
- `GET /api/v1/servers/{server_id}/health`
|
|
- `GET /api/v1/servers/{server_id}/metrics`
|
|
- `POST /api/v1/servers/{server_id}/services`
|
|
- `GET /api/v1/servers/{server_id}/services`
|
|
- `POST /api/v1/servers/{server_id}/services/{service_name}/restart`
|
|
- `GET /api/v1/servers/{server_id}/logs`
|
|
- `GET /api/v1/servers/{server_id}/logs/{service_name}`
|
|
- `GET /api/v1/actions`
|
|
- `GET /api/v1/audit`
|
|
|
|
## Current Status
|
|
|
|
This repository currently contains:
|
|
|
|
- architecture and API docs
|
|
- MVP roadmap and checklist
|
|
- runnable project scaffolding
|
|
- backend persistence, auth, users, and server registry foundation
|
|
- Alembic migration setup with a baseline revision for existing and new databases
|
|
- server health and metrics endpoints
|
|
- managed services, action history, and audit history foundation
|
|
- service log endpoints
|
|
- background worker that executes queued service actions
|
|
- structured request logging and stable error payloads with request IDs
|
|
- server-side token invalidation on logout and auth-relevant user changes
|
|
- Telegram link flow, bot commands, and bot-originated restart audit trail
|
|
- frontend login flow with session restore and token refresh
|
|
- frontend server registry view with add-server form for admins
|
|
- frontend server detail panels for health, metrics, services, logs, actions, and audit
|
|
- frontend settings section for Telegram link codes, test delivery, and unlink flow
|
|
- frontend edit flows for selected servers and managed services
|
|
- automated MVP acceptance flow for login -> Telegram link -> action -> audit
|
|
|
|
The next implementation step is:
|
|
|
|
- run a real deployment smoke on the target host and validate the documented rollback path
|
|
|
|
## Database Migrations
|
|
|
|
Alembic is now configured under `backend/alembic/`.
|
|
|
|
Useful commands:
|
|
|
|
```bash
|
|
cd backend
|
|
alembic upgrade head
|
|
```
|
|
|
|
For a Compose-based local stack, you can also run:
|
|
|
|
```bash
|
|
docker compose run --rm backend alembic upgrade head
|
|
```
|
|
|
|
The application still keeps a small runtime bootstrap for empty local databases,
|
|
but Alembic is now the intended path for schema changes going forward.
|
|
|
|
## Notes
|
|
|
|
- `GET /api/v1/servers/{server_id}/metrics` currently supports SSH servers only.
|
|
- `docker_api` and `agent` connection types remain reserved for later implementation.
|
|
- Telegram setup and command flow are documented in `docs/telegram.md`.
|