# 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`.