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

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:

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:

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:

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:

cd backend
alembic upgrade head

For a Compose-based local stack, you can also run:

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.