diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..a42468e --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,49 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - '.github/workflows/docs-deploy.yml' + workflow_dispatch: + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: read + deployments: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.12' + cache: 'pip' + cache-dependency-path: 'docs/requirements.txt' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + + - name: Build documentation + run: mkdocs build + + - name: Deploy to Cloudflare Pages + uses: cloudflare/pages-action@v1 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + projectName: chatops-docs + directory: site + gitHubToken: ${{ secrets.GITHUB_TOKEN }} + diff --git a/.gitignore b/.gitignore index 5d1cadc..2b243f4 100644 --- a/.gitignore +++ b/.gitignore @@ -81,3 +81,7 @@ htmlcov/ # Architecture ARCHITECTURE.md + +# Documentation +site/ +.cache/ \ No newline at end of file diff --git a/agent/INSTALLATION.md b/agent/INSTALLATION.md index 3410fb5..b648316 100644 --- a/agent/INSTALLATION.md +++ b/agent/INSTALLATION.md @@ -22,10 +22,10 @@ ```bash # Download the .deb package from GitHub Releases -wget https://github.com/martian56/chatops/releases/download/v1.0.3/chatops-agent_1.0.3_amd64.deb +wget https://github.com/martian56/chatops/releases/download/v1.0.4/chatops-agent_1.0.4_amd64.deb # Install the package -sudo dpkg -i chatops-agent_1.0.3_amd64.deb +sudo dpkg -i chatops-agent_1.0.4_amd64.deb sudo apt-get install -f # Install dependencies if needed # Edit the service file with your API key @@ -49,8 +49,8 @@ sudo systemctl status chatops-agent ```bash # Download from GitHub Releases -wget https://github.com/martian56/chatops/releases/download/v1.0.3/chatops-agent-linux-amd64-1.0.3.tar.gz -tar -xzf chatops-agent-linux-amd64-1.0.3.tar.gz +wget https://github.com/martian56/chatops/releases/download/v1.0.4/chatops-agent-linux-amd64-1.0.4.tar.gz +tar -xzf chatops-agent-linux-amd64-1.0.4.tar.gz # Run the agent ./chatops-agent-linux-amd64 -api-key YOUR_API_KEY_HERE diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..9a9a12c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +# Documentation +site/ +.cache/ \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f291de5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,58 @@ +# Documentation + +This directory contains the MkDocs documentation for ChatOps. + +## Building Locally + +### Prerequisites + +- Python 3.12+ +- pip + +### Setup + +```bash +# Install dependencies +pip install -r requirements-docs.txt + +# Serve documentation locally +mkdocs serve +``` + +The documentation will be available at `http://localhost:8000` + +### Build Static Site + +```bash +mkdocs build +``` + +The static site will be generated in the `site/` directory. + +## Documentation Structure + +- `index.md` - Homepage +- `getting-started/` - Getting started guides +- `architecture/` - System architecture +- `api/` - API documentation +- `agent/` - Agent documentation +- `frontend/` - Frontend documentation +- `technologies/` - Technology stack +- `deployment/` - Deployment guides +- `contributing/` - Contribution guidelines + +## Deployment + +Documentation is automatically deployed to Cloudflare Pages on push to `main` branch. + +See `.github/workflows/docs-deploy.yml` for deployment configuration. + +## Contributing + +When adding or updating documentation: + +1. Edit the relevant `.md` file +2. Test locally with `mkdocs serve` +3. Commit and push +4. Documentation will be automatically deployed + diff --git a/docs/agent/configuration.md b/docs/agent/configuration.md new file mode 100644 index 0000000..2053bab --- /dev/null +++ b/docs/agent/configuration.md @@ -0,0 +1,65 @@ +# Agent Configuration + +Configuration options for the ChatOps agent. + +## Configuration Methods + +### Command-line Flags + +```bash +./chatops-agent \ + -api-key YOUR_API_KEY \ + -api-url https://your-chatops-instance.com +``` + +### Environment Variables + +```bash +export CHATOPS_API_KEY="your-api-key-here" +export CHATOPS_API_URL="https://your-chatops-instance.com" +./chatops-agent +``` + +### Config File + +Create a JSON config file: + +```json +{ + "api_key": "your-api-key-here", + "api_url": "https://your-chatops-instance.com" +} +``` + +Use with: +```bash +./chatops-agent -config /path/to/config.json +``` + +## Configuration Options + +### API Key + +- **Required**: Yes +- **Flag**: `-api-key` +- **Env**: `CHATOPS_API_KEY` +- **Description**: API key for authentication + +### API URL + +- **Required**: No (default: https://chatops.onrender.com) +- **Flag**: `-api-url` +- **Env**: `CHATOPS_API_URL` +- **Description**: ChatOps API server URL + +## Defaults + +- **API URL**: `https://chatops.onrender.com` +- **Metrics Interval**: 5 seconds +- **Reconnection Delay**: Exponential backoff starting at 1 second + +## Next Steps + +- [Installation Guide](installation.md) +- [Development Guide](development.md) + diff --git a/docs/agent/development.md b/docs/agent/development.md new file mode 100644 index 0000000..188f09c --- /dev/null +++ b/docs/agent/development.md @@ -0,0 +1,54 @@ +# Agent Development + +Development guide for the ChatOps agent. + +## Prerequisites + +- Go 1.24+ +- Docker (optional, for testing Docker features) + +## Building + +```bash +cd agent +go build -o chatops-agent ./main.go +``` + +## Running Locally + +```bash +./chatops-agent -api-key YOUR_API_KEY -api-url http://localhost:8000 +``` + +## Project Structure + +``` +agent/ +├── main.go # Entry point +├── internal/ +│ ├── agent/ # Agent core logic +│ ├── api/ # API client +│ ├── config/ # Configuration +│ ├── metrics/ # Metrics collection +│ └── pkg/ # Shared packages +└── package/ # Packaging scripts +``` + +## Testing + +```bash +go test ./... +``` + +## Contributing + +1. Follow Go best practices +2. Write tests for new features +3. Update documentation +4. Submit pull request + +## Next Steps + +- [Installation Guide](installation.md) +- [Configuration Guide](configuration.md) + diff --git a/docs/agent/index.md b/docs/agent/index.md new file mode 100644 index 0000000..69cc6fa --- /dev/null +++ b/docs/agent/index.md @@ -0,0 +1,122 @@ +# Agent Documentation + +The ChatOps agent is a lightweight Go application that runs on each monitored server. + +## Overview + +The agent is responsible for: + +- **Metrics Collection**: CPU, memory, disk, and network metrics every 5 seconds +- **Docker Management**: Container lifecycle operations +- **Command Execution**: Remote command execution via WebSocket +- **Real-time Communication**: Bidirectional WebSocket connection to API + +## Features + +- ✅ Lightweight and efficient (single binary) +- ✅ Low resource usage +- ✅ Automatic reconnection +- ✅ Secure API key authentication +- ✅ Docker integration +- ✅ System metrics collection +- ✅ Command execution with output capture + +## Architecture + +``` +┌─────────────────────────────────────────┐ +│ Go Agent │ +├─────────────────────────────────────────┤ +│ Components │ +│ ├── Metrics Collector │ +│ │ ├── CPU │ +│ │ ├── Memory │ +│ │ ├── Disk │ +│ │ └── Network │ +│ ├── Docker Client │ +│ ├── WebSocket Client │ +│ └── Command Executor │ +├─────────────────────────────────────────┤ +│ Communication │ +│ ├── WebSocket Connection │ +│ ├── Authentication (API Key) │ +│ └── Message Protocol │ +└─────────────────────────────────────────┘ +``` + +## Quick Start + +1. **Get an API Key**: Create one in the web interface +2. **Download Agent**: Get the binary for your platform +3. **Run Agent**: `./chatops-agent -api-key YOUR_KEY` +4. **Verify**: Check the web interface for metrics + +See [Installation Guide](installation.md) for detailed instructions. + +## Configuration + +The agent can be configured via: + +- **Command-line flags**: `-api-key`, `-api-url` +- **Environment variables**: `CHATOPS_API_KEY`, `CHATOPS_API_URL` +- **Config file**: JSON configuration file (optional) + +See [Configuration Guide](configuration.md) for details. + +## Communication Protocol + +### Agent → API + +**Message Types**: +- `auth`: Initial authentication +- `metrics`: System metrics data +- `command_response`: Command execution result +- `docker_response`: Docker operation result + +### API → Agent + +**Message Types**: +- `auth_success`: Authentication confirmation +- `command`: Command execution request +- `docker_command`: Docker operation request + +## Metrics Collection + +The agent collects the following metrics every 5 seconds: + +- **CPU**: Usage percentage per core +- **Memory**: Total, used, available, percentage +- **Disk**: Usage per filesystem +- **Network**: Bytes sent/received per interface + +## Docker Support + +The agent can manage Docker containers if Docker is installed: + +- List containers +- Start/stop/restart containers +- Get container logs +- Container status information + +## Security + +- **API Key Authentication**: Secure key-based authentication +- **WebSocket Encryption**: TLS/SSL encryption in production +- **No Root Required**: Agent can run as non-root user +- **Minimal Permissions**: Only requires necessary system access + +## Troubleshooting + +Common issues and solutions: + +- **Connection Failed**: Check API URL and network connectivity +- **Authentication Failed**: Verify API key is correct and active +- **No Metrics**: Ensure agent has necessary system permissions +- **Docker Not Working**: Verify Docker is installed and accessible + +## Next Steps + +- [Installation Guide](installation.md) +- [Configuration Guide](configuration.md) +- [Development Guide](development.md) + diff --git a/docs/agent/installation.md b/docs/agent/installation.md new file mode 100644 index 0000000..d1d3668 --- /dev/null +++ b/docs/agent/installation.md @@ -0,0 +1,176 @@ +# Agent Installation + +Complete installation guide for the ChatOps agent. + +## Prerequisites + +- Linux/Unix system (x86_64 or ARM64) +- Network access to ChatOps API +- Optional: Docker installed for container management + +## Installation Methods + +### Method 1: Debian/Ubuntu Package (Recommended) + +```bash +# Download the .deb package +wget https://github.com/martian56/chatops/releases/download/v1.0.4/chatops-agent_1.0.4_amd64.deb + +# Install the package +sudo dpkg -i chatops-agent_1.0.4_amd64.deb +sudo apt-get install -f # Install dependencies if needed + +# Configure the API key +sudo systemctl edit chatops-agent.service +# Add: Environment="CHATOPS_API_KEY=your-api-key-here" + +# Or edit the service file directly +sudo nano /usr/lib/systemd/system/chatops-agent.service +# Replace YOUR_API_KEY_HERE with your actual API key + +# Start the service +sudo systemctl daemon-reload +sudo systemctl enable chatops-agent +sudo systemctl start chatops-agent + +# Check status +sudo systemctl status chatops-agent +``` + +### Method 2: Binary Installation + +```bash +# Download the binary archive +wget https://github.com/martian56/chatops/releases/download/v1.0.4/chatops-agent-linux-amd64-1.0.4.tar.gz +tar -xzf chatops-agent-linux-amd64-1.0.4.tar.gz + +# Run the agent +./chatops-agent-linux-amd64 -api-key YOUR_API_KEY_HERE +``` + +### Method 3: Build from Source + +```bash +# Clone the repository +git clone https://github.com/martian56/chatops.git +cd chatops/agent + +# Build the agent +go build -o chatops-agent ./main.go + +# Run the agent +./chatops-agent -api-key YOUR_API_KEY_HERE +``` + +## Configuration + +### Environment Variables + +```bash +export CHATOPS_API_KEY="your-api-key-here" +export CHATOPS_API_URL="https://your-chatops-instance.com" # Optional +./chatops-agent +``` + +### Command-line Flags + +```bash +./chatops-agent \ + -api-key YOUR_API_KEY \ + -api-url https://your-chatops-instance.com +``` + +## Running as a Service + +### systemd Service + +Create `/etc/systemd/system/chatops-agent.service`: + +```ini +[Unit] +Description=ChatOps Agent +After=network.target + +[Service] +Type=simple +User=your-user +WorkingDirectory=/path/to/agent +Environment="CHATOPS_API_KEY=your-api-key-here" +Environment="CHATOPS_API_URL=https://your-chatops-instance.com" +ExecStart=/path/to/agent/chatops-agent +Restart=always +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable chatops-agent +sudo systemctl start chatops-agent +``` + +### Windows Service + +Use NSSM (Non-Sucking Service Manager) or Task Scheduler. + +## Verification + +1. Check agent logs: + ```bash + sudo journalctl -u chatops-agent -f + ``` + +2. Verify in web interface: + - Server status should show "ONLINE" + - Metrics should appear in real-time + - Docker containers should be listed (if Docker installed) + +## Uninstallation + +### Debian/Ubuntu Package + +```bash +sudo systemctl stop chatops-agent +sudo systemctl disable chatops-agent +sudo dpkg -r chatops-agent +``` + +### Binary Installation + +```bash +# Stop the agent +pkill chatops-agent + +# Remove files +rm -f chatops-agent chatops-agent-linux-* +``` + +## Troubleshooting + +### Connection Issues + +- Verify API URL is correct +- Check network connectivity +- Ensure firewall allows outbound connections + +### Authentication Issues + +- Verify API key is correct +- Check API key is active in web interface +- Ensure API key hasn't been revoked + +### Metrics Not Appearing + +- Wait a few seconds (metrics sent every 5 seconds) +- Check agent logs for errors +- Verify agent has necessary system permissions + +## Next Steps + +- [Configuration Guide](configuration.md) +- [Development Guide](development.md) + diff --git a/docs/api/api-keys.md b/docs/api/api-keys.md new file mode 100644 index 0000000..f3d06a5 --- /dev/null +++ b/docs/api/api-keys.md @@ -0,0 +1,53 @@ +# API Keys + +API keys are used for agent authentication. + +## Creating API Keys + +1. Log into the web interface +2. Navigate to a server +3. Go to the "API Keys" tab +4. Click "Create API Key" +5. **Copy the key immediately** - it's only shown once! + +## Using API Keys + +Agents use API keys to authenticate via WebSocket: + +```json +{ + "type": "auth", + "api_key": "your-api-key-here" +} +``` + +## Security Best Practices + +1. **Never commit API keys** to version control +2. **Rotate keys regularly** +3. **Revoke compromised keys** immediately +4. **Use one key per server** +5. **Store keys securely** (environment variables, secrets manager) + +## Revoking API Keys + +You can revoke an API key at any time: + +1. Navigate to the server +2. Go to "API Keys" tab +3. Click "Revoke" next to the key + +Once revoked, the agent will be disconnected and cannot reconnect. + +## Key Format + +API keys follow the format: +``` +chatops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +## Next Steps + +- [Authentication Guide](authentication.md) +- [WebSocket API](websocket-api.md) + diff --git a/docs/api/authentication.md b/docs/api/authentication.md new file mode 100644 index 0000000..6abf718 --- /dev/null +++ b/docs/api/authentication.md @@ -0,0 +1,134 @@ +# Authentication + +ChatOps uses JWT tokens for user authentication and API keys for agent authentication. + +## User Authentication (JWT) + +### Registration + +```http +POST /api/v1/auth/register +Content-Type: application/json + +{ + "email": "user@example.com", + "username": "username", + "password": "password123", + "password_confirm": "password123", + "full_name": "Full Name" +} +``` + +**Response**: +```json +{ + "user": { + "id": "uuid", + "email": "user@example.com", + "username": "username", + "full_name": "Full Name" + }, + "access_token": "jwt_access_token", + "refresh_token": "jwt_refresh_token", + "token_type": "bearer" +} +``` + +### Login + +```http +POST /api/v1/auth/login +Content-Type: application/x-www-form-urlencoded + +username=username&password=password123 +``` + +**Response**: +```json +{ + "access_token": "jwt_access_token", + "refresh_token": "jwt_refresh_token", + "token_type": "bearer" +} +``` + +### Using Access Token + +Include the access token in the `Authorization` header: + +```http +GET /api/v1/servers +Authorization: Bearer jwt_access_token +``` + +### Refresh Token + +Access tokens expire after 30 minutes. Use the refresh token to get a new access token: + +```http +POST /api/v1/auth/refresh +Content-Type: application/json + +{ + "refresh_token": "jwt_refresh_token" +} +``` + +**Response**: +```json +{ + "access_token": "new_jwt_access_token", + "token_type": "bearer" +} +``` + +## Agent Authentication (API Keys) + +### Creating an API Key + +1. Log into the web interface +2. Navigate to a server +3. Go to the "API Keys" tab +4. Click "Create API Key" +5. Copy the key immediately (only shown once) + +### Using API Key + +Agents authenticate via WebSocket by sending an authentication message: + +```json +{ + "type": "auth", + "api_key": "your-api-key-here" +} +``` + +The API responds with: + +```json +{ + "type": "auth_success", + "server_id": "server-uuid", + "message": "Connected successfully" +} +``` + +## Token Expiration + +- **Access Token**: 30 minutes +- **Refresh Token**: 7 days + +## Security Best Practices + +1. **Never commit tokens or API keys** to version control +2. **Use HTTPS** in production +3. **Rotate API keys** regularly +4. **Store tokens securely** in the frontend (localStorage or httpOnly cookies) +5. **Revoke compromised keys** immediately + +## Next Steps + +- [REST Endpoints](rest-endpoints.md) +- [WebSocket API](websocket-api.md) +- [API Keys](api-keys.md) + diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..d12f786 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,119 @@ +# API Reference + +Complete API documentation for ChatOps REST and WebSocket APIs. + +## Base URL + +``` +https://your-chatops-instance.com/api/v1 +``` + +## Authentication + +ChatOps uses two authentication methods: + +1. **JWT Tokens**: For user authentication (REST API and frontend WebSockets) +2. **API Keys**: For agent authentication (agent WebSocket connections) + +See [Authentication Guide](authentication.md) for details. + +## API Endpoints + +### Authentication +- `POST /auth/register` - Register new user +- `POST /auth/login` - Login and get tokens +- `POST /auth/refresh` - Refresh access token +- `GET /auth/me` - Get current user +- `PUT /auth/me` - Update profile +- `POST /auth/change-password` - Change password +- `POST /auth/logout` - Logout (invalidate refresh token) + +### Servers +- `GET /servers` - List all servers +- `POST /servers` - Create server +- `GET /servers/{id}` - Get server details +- `PUT /servers/{id}` - Update server +- `DELETE /servers/{id}` - Delete server + +### Metrics +- `GET /metrics/{server_id}` - Get latest metrics +- `GET /metrics/{server_id}/history` - Get metrics history + +### Docker +- `GET /docker/{server_id}/containers` - List containers +- `POST /docker/{server_id}/containers/{container_id}/start` - Start container +- `POST /docker/{server_id}/containers/{container_id}/stop` - Stop container +- `POST /docker/{server_id}/containers/{container_id}/restart` - Restart container +- `GET /docker/{server_id}/containers/{container_id}/logs` - Get container logs + +### Commands +- `POST /commands/{server_id}` - Execute command + +### Alerts +- `GET /alerts` - List alerts +- `GET /alerts/{id}` - Get alert details +- `POST /alerts/{id}/resolve` - Resolve alert +- `GET /alerts/thresholds` - List alert thresholds +- `POST /alerts/thresholds` - Create alert threshold +- `PUT /alerts/thresholds/{id}` - Update alert threshold +- `DELETE /alerts/thresholds/{id}` - Delete alert threshold + +### API Keys +- `GET /api-keys/me` - Get my API keys +- `POST /api-keys` - Create API key +- `DELETE /api-keys/{id}` - Revoke API key + +### WebSocket +- `WS /agents/ws` - Agent WebSocket endpoint +- `WS /ws/metrics/{server_id}` - Frontend metrics WebSocket +- `WS /ws/logs/{server_id}` - Frontend logs WebSocket + +## Interactive Documentation + +When running the API server, interactive documentation is available at: + +- **Swagger UI**: `/docs` +- **ReDoc**: `/redoc` + +## Response Format + +### Success Response + +```json +{ + "data": { ... }, + "message": "Success message (optional)" +} +``` + +### Error Response + +```json +{ + "detail": "Error message", + "status_code": 400 +} +``` + +## Status Codes + +- `200` - Success +- `201` - Created +- `400` - Bad Request +- `401` - Unauthorized +- `403` - Forbidden +- `404` - Not Found +- `422` - Validation Error +- `500` - Internal Server Error + +## Rate Limiting + +Rate limiting is not currently implemented but planned for future versions. + +## Next Steps + +- [Authentication Guide](authentication.md) +- [REST Endpoints](rest-endpoints.md) +- [WebSocket API](websocket-api.md) +- [API Keys](api-keys.md) + diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md new file mode 100644 index 0000000..6ee8438 --- /dev/null +++ b/docs/api/rest-endpoints.md @@ -0,0 +1,321 @@ +# REST API Endpoints + +Complete reference for all REST API endpoints. + +## Base URL + +``` +https://your-chatops-instance.com/api/v1 +``` + +## Authentication + +Most endpoints require authentication. Include the JWT token in the `Authorization` header: + +``` +Authorization: Bearer your_access_token +``` + +## Servers + +### List Servers + +```http +GET /servers +Authorization: Bearer {token} +``` + +**Response**: +```json +[ + { + "id": "uuid", + "name": "Production Server", + "host": "192.168.1.100", + "port": 22, + "status": "online", + "created_at": "2024-01-01T00:00:00Z" + } +] +``` + +### Create Server + +```http +POST /servers +Authorization: Bearer {token} +Content-Type: application/json + +{ + "name": "New Server", + "host": "192.168.1.101", + "port": 22 +} +``` + +### Get Server + +```http +GET /servers/{id} +Authorization: Bearer {token} +``` + +### Update Server + +```http +PUT /servers/{id} +Authorization: Bearer {token} +Content-Type: application/json + +{ + "name": "Updated Name" +} +``` + +### Delete Server + +```http +DELETE /servers/{id} +Authorization: Bearer {token} +``` + +## Metrics + +### Get Latest Metrics + +```http +GET /metrics/{server_id} +Authorization: Bearer {token} +``` + +**Response**: +```json +{ + "server_id": "uuid", + "cpu_percent": 45.2, + "memory_percent": 62.5, + "disk_usage": [ + { + "path": "/", + "total": 1000000000, + "used": 500000000, + "free": 500000000, + "percent": 50.0 + } + ], + "network": [ + { + "interface": "eth0", + "bytes_sent": 1000000, + "bytes_recv": 2000000 + } + ], + "timestamp": "2024-01-01T00:00:00Z" +} +``` + +### Get Metrics History + +```http +GET /metrics/{server_id}/history?start=2024-01-01T00:00:00Z&end=2024-01-01T23:59:59Z +Authorization: Bearer {token} +``` + +## Docker + +### List Containers + +```http +GET /docker/{server_id}/containers +Authorization: Bearer {token} +``` + +### Start Container + +```http +POST /docker/{server_id}/containers/{container_id}/start +Authorization: Bearer {token} +``` + +### Stop Container + +```http +POST /docker/{server_id}/containers/{container_id}/stop?timeout=10 +Authorization: Bearer {token} +``` + +### Restart Container + +```http +POST /docker/{server_id}/containers/{container_id}/restart?timeout=10 +Authorization: Bearer {token} +``` + +### Get Container Logs + +```http +GET /docker/{server_id}/containers/{container_id}/logs?tail=100 +Authorization: Bearer {token} +``` + +## Commands + +### Execute Command + +```http +POST /commands/{server_id} +Authorization: Bearer {token} +Content-Type: application/json + +{ + "command": "ls -la" +} +``` + +**Response**: +```json +{ + "command_id": "uuid", + "command": "ls -la", + "output": "total 100\n...", + "exit_code": 0, + "duration_ms": 150 +} +``` + +## Alerts + +### List Alerts + +```http +GET /alerts?status=active&server_id={uuid} +Authorization: Bearer {token} +``` + +### Resolve Alert + +```http +POST /alerts/{id}/resolve +Authorization: Bearer {token} +``` + +### List Thresholds + +```http +GET /alerts/thresholds?server_id={uuid} +Authorization: Bearer {token} +``` + +### Create Threshold + +```http +POST /alerts/thresholds +Authorization: Bearer {token} +Content-Type: application/json + +{ + "server_id": "uuid", + "metric_type": "cpu", + "threshold_value": 80.0, + "comparison": "gt", + "enabled": true +} +``` + +## API Keys + +### List My API Keys + +```http +GET /api-keys/me +Authorization: Bearer {token} +``` + +### Create API Key + +```http +POST /api-keys +Authorization: Bearer {token} +Content-Type: application/json + +{ + "server_id": "uuid", + "name": "Production Agent" +} +``` + +**Response**: +```json +{ + "id": "uuid", + "name": "Production Agent", + "server_id": "uuid", + "key": "chatops_xxxxxxxxxxxx", // Only shown once! + "created_at": "2024-01-01T00:00:00Z" +} +``` + +### Revoke API Key + +```http +DELETE /api-keys/{id} +Authorization: Bearer {token} +``` + +## Error Responses + +All endpoints may return the following error responses: + +### 400 Bad Request +```json +{ + "detail": "Invalid request" +} +``` + +### 401 Unauthorized +```json +{ + "detail": "Could not validate credentials" +} +``` + +### 403 Forbidden +```json +{ + "detail": "Not enough permissions" +} +``` + +### 404 Not Found +```json +{ + "detail": "Resource not found" +} +``` + +### 422 Validation Error +```json +{ + "detail": [ + { + "loc": ["body", "name"], + "msg": "field required", + "type": "value_error.missing" + } + ] +} +``` + +## Interactive Documentation + +For interactive API documentation, visit: +- `/docs` - Swagger UI +- `/redoc` - ReDoc + +## Next Steps + +- [WebSocket API](websocket-api.md) +- [API Keys](api-keys.md) +- [Authentication](authentication.md) + diff --git a/docs/api/websocket-api.md b/docs/api/websocket-api.md new file mode 100644 index 0000000..d300cf1 --- /dev/null +++ b/docs/api/websocket-api.md @@ -0,0 +1,225 @@ +# WebSocket API + +Real-time communication via WebSocket connections. + +## Endpoints + +### Agent WebSocket + +``` +WS /api/v1/agents/ws +``` + +**Authentication**: API key in initial message + +**Purpose**: Agent connection for metrics and commands + +### Frontend Metrics WebSocket + +``` +WS /api/v1/ws/metrics/{server_id} +``` + +**Authentication**: JWT token in initial message + +**Purpose**: Real-time metrics updates for frontend + +### Frontend Logs WebSocket + +``` +WS /api/v1/ws/logs/{server_id} +``` + +**Authentication**: JWT token in initial message + +**Purpose**: Real-time log streaming for frontend + +## Agent WebSocket Protocol + +### Connection + +1. Connect to `/api/v1/agents/ws` +2. Send authentication message: + ```json + { + "type": "auth", + "api_key": "your-api-key-here" + } + ``` +3. Receive authentication response: + ```json + { + "type": "auth_success", + "server_id": "uuid", + "message": "Connected successfully" + } + ``` + +### Sending Metrics + +Send metrics every 5 seconds: + +```json +{ + "type": "metrics", + "server_id": "uuid", + "cpu_percent": 45.2, + "memory_percent": 62.5, + "disk_usage": [...], + "network": [...], + "timestamp": "2024-01-01T00:00:00Z" +} +``` + +### Receiving Commands + +```json +{ + "type": "command", + "command_id": "uuid", + "command": "ls -la" +} +``` + +### Sending Command Response + +```json +{ + "type": "command_response", + "command_id": "uuid", + "output": "total 100\n...", + "exit_code": 0, + "duration_ms": 150 +} +``` + +### Docker Commands + +Receive: +```json +{ + "type": "docker_command", + "command_id": "uuid", + "action": "start", + "container_id": "container-id" +} +``` + +Respond: +```json +{ + "type": "docker_response", + "command_id": "uuid", + "success": true, + "message": "Container started" +} +``` + +## Frontend WebSocket Protocol + +### Metrics WebSocket + +1. Connect to `/api/v1/ws/metrics/{server_id}` +2. Send authentication: + ```json + { + "type": "auth", + "token": "jwt-access-token" + } + ``` +3. Receive metrics updates: + ```json + { + "type": "metrics", + "data": { + "cpu_percent": 45.2, + "memory_percent": 62.5, + ... + } + } + ``` + +### Logs WebSocket + +1. Connect to `/api/v1/ws/logs/{server_id}` +2. Send authentication: + ```json + { + "type": "auth", + "token": "jwt-access-token" + } + ``` +3. Receive log entries: + ```json + { + "type": "log", + "data": { + "level": "INFO", + "message": "Log message", + "timestamp": "2024-01-01T00:00:00Z" + } + } + ``` + +## Message Types + +### Agent Messages + +- `auth`: Authentication request +- `auth_success`: Authentication confirmation +- `metrics`: Metrics data +- `command`: Command execution request +- `command_response`: Command execution result +- `docker_command`: Docker operation request +- `docker_response`: Docker operation result + +### Frontend Messages + +- `auth`: Authentication request +- `metrics`: Metrics update +- `log`: Log entry +- `alert`: Alert notification +- `error`: Error message + +## Error Handling + +### Authentication Failed + +```json +{ + "type": "error", + "message": "Invalid or inactive API key" +} +``` + +### Invalid Message + +```json +{ + "type": "error", + "message": "Invalid message format" +} +``` + +## Reconnection + +Both agents and frontend clients should implement automatic reconnection: + +1. Detect connection loss +2. Wait for exponential backoff +3. Reconnect and re-authenticate +4. Resume normal operation + +## Best Practices + +1. **Always authenticate first** before sending other messages +2. **Handle reconnections** gracefully +3. **Validate message types** before processing +4. **Implement heartbeat** to detect connection issues +5. **Use TLS/SSL** in production + +## Next Steps + +- [REST Endpoints](rest-endpoints.md) +- [API Keys](api-keys.md) + diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md new file mode 100644 index 0000000..510501a --- /dev/null +++ b/docs/architecture/data-flow.md @@ -0,0 +1,306 @@ +# Data Flow + +Detailed data flow diagrams and explanations for ChatOps operations. + +## Metrics Collection Flow + +``` +┌─────────┐ +│ Agent │ +└────┬────┘ + │ Collects metrics every 5 seconds + │ (CPU, Memory, Disk, Network) + ↓ +┌─────────────────────┐ +│ WebSocket Client │ +│ (Agent) │ +└────┬────────────────┘ + │ Sends metrics via WebSocket + ↓ +┌─────────────────────┐ +│ API Endpoint │ +│ /agents/ws │ +└────┬────────────────┘ + │ + ├──→ AgentManager + │ ├── Register connection + │ └── Store metrics + │ + ├──→ Database (PostgreSQL) + │ └── Store metrics with timestamp + │ + ├──→ AlertService + │ ├── Check thresholds + │ ├── Create alerts if needed + │ └── Resolve alerts if conditions normalize + │ + └──→ WSManager + └── Broadcast to frontend clients + ↓ + ┌─────────────────────┐ + │ Frontend Clients │ + │ (WebSocket) │ + └─────────────────────┘ + ↓ + ┌─────────────────────┐ + │ UI Updates │ + │ (Charts, Metrics) │ + └─────────────────────┘ +``` + +## Command Execution Flow + +``` +┌──────────────┐ +│ Frontend │ +│ (User) │ +└──────┬───────┘ + │ User enters command + ↓ +┌─────────────────────┐ +│ REST API │ +│ POST /commands/ │ +└──────┬──────────────┘ + │ + ├──→ Authentication (JWT) + ├──→ Authorization (User owns server) + └──→ Command Service + │ + ├──→ AgentManager + │ ├── Find agent connection + │ └── Send command via WebSocket + │ ↓ + └──→ Agent + │ Receives command + ├──→ Execute command + ├──→ Capture output + └──→ Send response + ↓ + ┌─────────────────────┐ + │ WebSocket Response │ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ AgentManager │ + │ (Receives response)│ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ Database │ + │ (Store history) │ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ REST Response │ + │ (Return to User) │ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ Frontend │ + │ (Display output) │ + └─────────────────────┘ +``` + +## Docker Operations Flow + +``` +┌──────────────┐ +│ Frontend │ +│ (User) │ +└──────┬───────┘ + │ User clicks container action + │ (Start, Stop, Restart, etc.) + ↓ +┌─────────────────────┐ +│ REST API │ +│ POST /docker/ │ +│ /containers/{id}/ │ +│ {action} │ +└──────┬──────────────┘ + │ + ├──→ Authentication (JWT) + ├──→ Authorization (User owns server) + └──→ Docker Service + │ + ├──→ AgentManager + │ ├── Find agent connection + │ └── Send Docker command via WebSocket + │ ↓ + └──→ Agent + │ Receives Docker command + ├──→ Docker Client + │ ├── Execute Docker operation + │ └── Get container status + └──→ Send response + ↓ + ┌─────────────────────┐ + │ WebSocket Response │ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ REST Response │ + │ (Return to User) │ + └──────┬──────────────┘ + ↓ + ┌─────────────────────┐ + │ Frontend │ + │ (Update UI) │ + └─────────────────────┘ +``` + +## Authentication Flow + +### User Login + +``` +┌──────────────┐ +│ Frontend │ +└──────┬───────┘ + │ POST /auth/login + │ {username, password} + ↓ +┌─────────────────────┐ +│ Auth Service │ +└──────┬──────────────┘ + │ + ├──→ Verify credentials + ├──→ Generate JWT tokens + │ ├── Access token (30 min) + │ └── Refresh token (7 days) + └──→ Return tokens + ↓ +┌─────────────────────┐ +│ Frontend │ +│ (Store tokens) │ +└─────────────────────┘ +``` + +### Agent Authentication + +``` +┌─────────┐ +│ Agent │ +└────┬────┘ + │ Connect to /agents/ws + │ Send: {"type": "auth", "api_key": "..."} + ↓ +┌─────────────────────┐ +│ API Endpoint │ +│ /agents/ws │ +└────┬────────────────┘ + │ + ├──→ Verify API key + │ ├── Check database + │ ├── Verify active status + │ └── Get server_id + │ + ├──→ Register agent + │ ├── AgentManager.register_agent() + │ └── Update server status to ONLINE + │ + └──→ Send auth_success + ↓ + ┌─────────────────────┐ + │ Agent │ + │ (Start sending │ + │ metrics) │ + └─────────────────────┘ +``` + +## Alert Evaluation Flow + +``` +┌─────────────────────┐ +│ Metrics Received │ +└──────┬──────────────┘ + ↓ +┌─────────────────────┐ +│ AlertService │ +└──────┬──────────────┘ + │ + ├──→ Fetch thresholds for server + ├──→ Evaluate each threshold + │ ├── Compare metric value + │ ├── Check comparison operator (>, <, =) + │ └── Check if threshold enabled + │ + ├──→ If threshold exceeded: + │ ├── Check if alert already exists + │ ├── Create new alert if not exists + │ └── Log alert creation + │ + └──→ If threshold normalized: + ├── Find active alert + ├── Resolve alert + └── Log alert resolution + ↓ + ┌─────────────────────┐ + │ Database │ + │ (Store alert) │ + └─────────────────────┘ + ↓ + ┌─────────────────────┐ + │ Frontend │ + │ (Display alert) │ + └─────────────────────┘ +``` + +## Real-time Updates Flow + +``` +┌─────────┐ +│ Agent │ +└────┬────┘ + │ Sends metrics + ↓ +┌─────────────────────┐ +│ API (AgentManager) │ +└──────┬──────────────┘ + │ + ├──→ Store in database + └──→ WSManager.broadcast_metrics() + │ + ├──→ Get all subscribers for server_id + ├──→ For each WebSocket connection: + │ └──→ Send metrics JSON + │ ↓ + └──→ Frontend Clients + │ Receive metrics + ├──→ Update TanStack Query cache + ├──→ Update Zustand store + └──→ Re-render UI components + ├── Charts update + ├── Metrics display updates + └── Status indicators update +``` + +## Error Handling Flow + +``` +┌─────────────────────┐ +│ Operation Fails │ +└──────┬──────────────┘ + │ + ├──→ Try/Catch block + ├──→ Log error + │ ├── Error message + │ ├── Stack trace + │ └── Context (user, server, etc.) + │ + ├──→ Return appropriate HTTP status + │ ├── 400: Bad Request + │ ├── 401: Unauthorized + │ ├── 403: Forbidden + │ ├── 404: Not Found + │ └── 500: Internal Server Error + │ + └──→ Frontend handles error + ├── Display error message + └── Log for debugging +``` + +## Next Steps + +- [System Architecture](system-architecture.md) +- [Future Architecture](future-architecture.md) + diff --git a/docs/architecture/future-architecture.md b/docs/architecture/future-architecture.md new file mode 100644 index 0000000..23baefc --- /dev/null +++ b/docs/architecture/future-architecture.md @@ -0,0 +1,154 @@ +# Future Architecture + +Planned architecture improvements for ChatOps v2.0 and beyond. + +## Overview + +The future architecture introduces: +- **Kafka** for event streaming +- **Redis** for distributed caching and state +- **Microservices** for better scalability +- **TimescaleDB** for optimized time-series storage + +## Key Improvements + +### 1. Kafka Integration + +**Purpose**: Decouple services, enable event streaming, handle high throughput + +**Topics**: +- `metrics-topic`: All metrics from agents (partitioned by server_id) +- `alerts-topic`: Alert creation/resolution events +- `commands-topic`: Command execution requests/responses +- `events-topic`: Connection events, audit logs, system events +- `logs-topic`: Application and system logs + +**Benefits**: +- **Buffering**: Metrics buffered if API is down +- **Scalability**: Multiple consumers can process metrics +- **Replay**: Replay events for debugging/recovery +- **Event Sourcing**: Complete event history + +### 2. Redis Integration + +**Purpose**: Distributed caching, state management, pub/sub + +**Use Cases**: +- **Agent Connection Registry**: `agent:connections:{server_id}` → connection metadata +- **Metrics Cache**: `metrics:latest:{server_id}` → latest metrics (TTL: 60s) +- **Session Store**: `session:{user_id}` → JWT refresh tokens +- **Rate Limiting**: `ratelimit:{user_id}:{endpoint}` → request counters +- **WebSocket Subscriptions**: `ws:subscribers:{server_id}` → Set of client IDs +- **Distributed Locks**: `lock:command:{server_id}` → prevent concurrent commands +- **Pub/Sub**: Real-time broadcasting to frontend clients + +### 3. Microservices Architecture + +**Service Breakdown**: + +1. **Auth Service**: JWT, API keys, user authentication +2. **Server Service**: Server CRUD operations +3. **Metrics Service**: Metrics storage and retrieval +4. **Alert Service**: Threshold evaluation and alert management +5. **Command Service**: Command execution and routing +6. **WebSocket Service**: WebSocket connection management +7. **Notification Service**: Alert notifications (Email, Slack, etc.) +8. **Analytics Service**: Real-time aggregations and ML + +### 4. TimescaleDB + +**Purpose**: Optimized time-series storage + +**Features**: +- Automatic partitioning by time +- Compression for old data +- Retention policies +- Continuous aggregates +- Better query performance + +## Migration Path + +### Phase 1: Add Redis (v1.5) +- Move agent connections to Redis +- Cache metrics in Redis +- Implement Redis pub/sub for real-time updates + +### Phase 2: Add Kafka (v1.8) +- Introduce Kafka for metrics ingestion +- Keep WebSocket for commands (temporary) +- Dual-write: WebSocket + Kafka +- Gradually migrate consumers + +### Phase 3: Microservices (v2.0) +- Split monolith into services +- Service-to-service via Kafka +- API Gateway for routing +- Service mesh for communication + +### Phase 4: TimescaleDB (v2.1) +- Migrate metrics to TimescaleDB +- Implement compression/retention +- Optimize queries with continuous aggregates + +## Technology Stack + +**Infrastructure**: +- **Container Orchestration**: Kubernetes +- **Service Mesh**: Istio or Linkerd +- **API Gateway**: Kong, Traefik, or AWS API Gateway +- **Load Balancer**: NGINX, HAProxy, or cloud LB +- **Monitoring**: Prometheus + Grafana +- **Logging**: ELK Stack or Loki +- **Tracing**: Jaeger or Zipkin + +**Message Queue**: +- **Kafka**: Event streaming, metrics ingestion +- **Redis Streams**: Lightweight alternative for some use cases + +**Caching**: +- **Redis Cluster**: Distributed caching, pub/sub +- **Redis Sentinel**: High availability + +**Database**: +- **PostgreSQL**: Primary database (users, servers, configs) +- **TimescaleDB**: Time-series metrics storage +- **Read Replicas**: For read-heavy operations + +## Scalability Benefits + +1. **Horizontal Scaling**: Each service can scale independently +2. **Fault Tolerance**: Service failures don't cascade +3. **High Throughput**: Kafka handles millions of metrics/second +4. **Low Latency**: Redis caching reduces database load +5. **Event Replay**: Debugging and recovery via Kafka +6. **Multi-Region**: Redis/Kafka support geo-distribution +7. **Cost Optimization**: Scale services based on load + +## Security Enhancements + +1. **API Gateway**: Centralized authentication/authorization +2. **Service Mesh**: mTLS between services +3. **Secrets Management**: Vault or AWS Secrets Manager +4. **Rate Limiting**: Redis-based distributed rate limiting +5. **Audit Logging**: All events to Kafka → Elasticsearch + +## Comparison: Current vs Future + +| Aspect | Current (v1.0) | Future (v2.0) | +|--------|----------------|---------------| +| **Scalability** | Single instance | Horizontal scaling | +| **State Management** | In-memory | Redis distributed | +| **Message Queue** | Direct WebSocket | Kafka event streaming | +| **Metrics Storage** | PostgreSQL | TimescaleDB | +| **Caching** | None | Redis cluster | +| **Service Architecture** | Monolith | Microservices | +| **Fault Tolerance** | Single point of failure | Service isolation | +| **Throughput** | Limited by single instance | Millions of events/sec | +| **Real-time Updates** | Direct WebSocket | Redis pub/sub + WebSocket | +| **Event History** | Database only | Kafka + Database | + +## Next Steps + +- [System Architecture](system-architecture.md) +- [Data Flow](data-flow.md) + diff --git a/docs/architecture/index.md b/docs/architecture/index.md new file mode 100644 index 0000000..9839943 --- /dev/null +++ b/docs/architecture/index.md @@ -0,0 +1,172 @@ +# Architecture Overview + +ChatOps follows a three-tier architecture designed for scalability, reliability, and real-time performance. + +## System Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PRESENTATION LAYER │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ React Web Frontend (Vite + TypeScript) │ │ +│ │ - TanStack Query (Data Fetching) │ │ +│ │ - Zustand (State Management) │ │ +│ │ - WebSocket Client (Real-time Updates) │ │ +│ │ - Tailwind CSS + Shadcn UI │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↕ HTTP/WebSocket +┌─────────────────────────────────────────────────────────────┐ +│ APPLICATION LAYER │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ FastAPI Backend (Python) │ │ +│ │ ├── REST API Endpoints │ │ +│ │ ├── WebSocket Endpoints │ │ +│ │ ├── Agent Manager (WebSocket Connections) │ │ +│ │ ├── WS Manager (Client Connections) │ │ +│ │ ├── Alert Service (Threshold Checking) │ │ +│ │ └── Auth Service (JWT + API Keys) │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↕ SQLAlchemy Async +┌─────────────────────────────────────────────────────────────┐ +│ DATA LAYER │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ PostgreSQL Database (Async via asyncpg) │ │ +│ │ ├── Users, Servers, API Keys │ │ +│ │ ├── Metrics (Time-series data) │ │ +│ │ ├── Alerts, Logs, Audit Logs │ │ +│ │ └── Command History, Connection Events │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↕ WebSocket +┌─────────────────────────────────────────────────────────────┐ +│ AGENT LAYER │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Go Agent (Lightweight Binary) │ │ +│ │ ├── Metrics Collector (CPU, Memory, Disk, Network) │ │ +│ │ ├── Docker Client (Container Management) │ │ +│ │ ├── WebSocket Client (Bidirectional) │ │ +│ │ └── Command Executor │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Components + +### 1. Web Frontend + +**Location**: `web/` + +- React 18 with TypeScript +- Vite for fast development and builds +- TanStack Query for server state management +- Zustand for client state +- WebSocket API for real-time updates +- Tailwind CSS + Shadcn UI for styling + +### 2. API Backend + +**Location**: `api/` + +- FastAPI (async Python web framework) +- SQLAlchemy async ORM +- PostgreSQL with asyncpg driver +- WebSocket support for real-time communication +- JWT authentication +- Alembic for database migrations + +### 3. Agent + +**Location**: `agent/` + +- Go 1.24+ binary +- Lightweight and efficient +- Docker client integration +- WebSocket client for bidirectional communication +- System metrics collection + +### 4. Database + +- PostgreSQL 16+ +- Async operations via asyncpg +- Time-series metrics storage +- Full audit logging + +## Data Flow + +### Metrics Collection + +``` +Agent → WebSocket → API Agent Endpoint → AgentManager + ↓ + Store in PostgreSQL + ↓ + Check Alert Thresholds + ↓ + Broadcast to Frontend (WSManager) + ↓ + Frontend Updates UI +``` + +### Command Execution + +``` +Frontend → REST API → AgentManager → Agent WebSocket + ↓ + Agent Executes Command + ↓ + Response via WebSocket + ↓ + AgentManager → Response Queue + ↓ + REST API Response → Frontend +``` + +## Key Design Decisions + +### Real-time Communication + +- **WebSockets** for bidirectional communication +- Separate endpoints for agents and frontend clients +- Message-based protocol for commands and responses + +### Authentication + +- **JWT tokens** for user authentication +- **API keys** for agent authentication +- Refresh token mechanism for session management + +### Database + +- **PostgreSQL** for relational data +- Async operations for better performance +- Time-series data stored with timestamps + +### Scalability + +- Stateless API design +- In-memory connection management (current) +- Future: Redis for distributed state + +## Current Limitations + +1. **In-Memory State**: Agent connections stored in memory +2. **Single Instance**: No horizontal scaling support +3. **No Message Queue**: Direct WebSocket communication +4. **Synchronous Alert Checking**: Alert checks during metric processing + +## Future Architecture + +See [Future Architecture](future-architecture.md) for planned improvements including: +- Kafka for event streaming +- Redis for distributed caching +- Microservices architecture +- TimescaleDB for metrics + +## Next Steps + +- [System Architecture Details](system-architecture.md) +- [Data Flow Diagrams](data-flow.md) +- [Future Architecture Plans](future-architecture.md) + diff --git a/docs/architecture/system-architecture.md b/docs/architecture/system-architecture.md new file mode 100644 index 0000000..5981e80 --- /dev/null +++ b/docs/architecture/system-architecture.md @@ -0,0 +1,273 @@ +# System Architecture + +Detailed system architecture documentation for ChatOps. + +## Component Overview + +### Frontend Architecture + +``` +┌─────────────────────────────────────────┐ +│ React Application │ +├─────────────────────────────────────────┤ +│ Pages │ +│ ├── Login/Register │ +│ ├── Servers List │ +│ ├── Server Detail │ +│ ├── Alerts │ +│ └── Settings │ +├─────────────────────────────────────────┤ +│ Components │ +│ ├── Charts (Recharts) │ +│ ├── Forms (Shadcn UI) │ +│ ├── Terminal │ +│ └── Layout Components │ +├─────────────────────────────────────────┤ +│ State Management │ +│ ├── Zustand (Auth, Servers) │ +│ └── TanStack Query (Server State) │ +├─────────────────────────────────────────┤ +│ API Layer │ +│ ├── REST Client (Axios) │ +│ └── WebSocket Client │ +└─────────────────────────────────────────┘ +``` + +### Backend Architecture + +``` +┌─────────────────────────────────────────┐ +│ FastAPI Application │ +├─────────────────────────────────────────┤ +│ API Routes (v1) │ +│ ├── /auth/* │ +│ ├── /servers/* │ +│ ├── /metrics/* │ +│ ├── /docker/* │ +│ ├── /commands/* │ +│ ├── /alerts/* │ +│ ├── /api-keys/* │ +│ ├── /agents/ws │ +│ └── /ws/* │ +├─────────────────────────────────────────┤ +│ Services │ +│ ├── AgentManager │ +│ ├── WSManager │ +│ ├── AlertService │ +│ ├── AuthService │ +│ └── AuditService │ +├─────────────────────────────────────────┤ +│ CRUD Layer │ +│ ├── User CRUD │ +│ ├── Server CRUD │ +│ ├── Metric CRUD │ +│ └── ... │ +├─────────────────────────────────────────┤ +│ Database Layer │ +│ └── SQLAlchemy Async │ +└─────────────────────────────────────────┘ +``` + +### Agent Architecture + +``` +┌─────────────────────────────────────────┐ +│ Go Agent │ +├─────────────────────────────────────────┤ +│ Components │ +│ ├── Metrics Collector │ +│ │ ├── CPU │ +│ │ ├── Memory │ +│ │ ├── Disk │ +│ │ └── Network │ +│ ├── Docker Client │ +│ ├── WebSocket Client │ +│ └── Command Executor │ +├─────────────────────────────────────────┤ +│ Communication │ +│ ├── WebSocket Connection │ +│ ├── Authentication (API Key) │ +│ └── Message Protocol │ +└─────────────────────────────────────────┘ +``` + +## Service Layer Details + +### AgentManager + +**Purpose**: Manages agent WebSocket connections + +**Responsibilities**: +- Register/unregister agent connections +- Route commands to agents +- Handle command responses +- Track agent status + +**Key Methods**: +- `register_agent(server_id, websocket)` +- `unregister_agent(server_id)` +- `send_command(server_id, command)` +- `get_agent_connection(server_id)` + +### WSManager + +**Purpose**: Manages frontend WebSocket connections + +**Responsibilities**: +- Register frontend clients +- Broadcast metrics to subscribers +- Broadcast logs to subscribers +- Handle client disconnections + +**Key Methods**: +- `connect(websocket, server_id, client_type)` +- `disconnect(websocket, server_id)` +- `broadcast_metrics(server_id, metrics)` +- `broadcast_logs(server_id, logs)` + +### AlertService + +**Purpose**: Manages alert threshold checking + +**Responsibilities**: +- Evaluate metrics against thresholds +- Create alerts when thresholds are exceeded +- Resolve alerts when conditions normalize +- Manage alert lifecycle + +**Key Methods**: +- `check_metrics_against_thresholds(server_id, metrics)` +- `create_alert(threshold, metric_value)` +- `resolve_alert(alert_id)` + +### AuthService + +**Purpose**: Handles authentication and authorization + +**Responsibilities**: +- JWT token generation +- Token validation +- API key verification +- Password hashing + +**Key Methods**: +- `create_access_token(user_id)` +- `verify_token(token)` +- `hash_password(password)` +- `verify_password(plain, hashed)` + +## Database Schema + +### Core Tables + +- **users**: User accounts and authentication +- **servers**: Server definitions +- **api_keys**: Agent authentication keys +- **metrics**: Time-series metrics data +- **alerts**: Alert instances +- **alert_thresholds**: Alert configurations +- **log_entries**: System and application logs +- **command_history**: Executed commands +- **connection_events**: Agent connection/disconnection events +- **audit_logs**: User action audit trail + +### Relationships + +``` +users ──┬── servers (owner) + ├── api_keys (creator) + └── audit_logs (actor) + +servers ──┬── api_keys + ├── metrics + ├── alerts + ├── alert_thresholds + ├── log_entries + ├── command_history + └── connection_events +``` + +## Communication Protocols + +### Agent → API + +**WebSocket Endpoint**: `/api/v1/agents/ws` + +**Authentication**: API key in initial message + +**Message Types**: +- `auth`: Initial authentication +- `metrics`: System metrics data +- `command_response`: Command execution result +- `docker_response`: Docker operation result + +### API → Agent + +**Message Types**: +- `auth_success`: Authentication confirmation +- `command`: Command execution request +- `docker_command`: Docker operation request + +### Frontend → API + +**REST Endpoints**: Standard HTTP methods + +**WebSocket Endpoints**: +- `/api/v1/ws/metrics/{server_id}`: Real-time metrics +- `/api/v1/ws/logs/{server_id}`: Real-time logs + +**Authentication**: JWT token in initial message + +## Security Architecture + +### Authentication Flow + +``` +User Login + ↓ +JWT Token Generated + ↓ +Token Stored (Frontend) + ↓ +Token Sent with Requests + ↓ +API Validates Token + ↓ +Request Processed +``` + +### API Key Flow + +``` +API Key Generated + ↓ +Key Stored (Database) + ↓ +Agent Connects with Key + ↓ +API Validates Key + ↓ +Agent Authenticated +``` + +## Performance Considerations + +### Current Optimizations + +- Async database operations +- WebSocket for real-time updates +- Connection pooling +- Efficient metrics storage + +### Future Optimizations + +- Redis caching layer +- Kafka for event streaming +- Database read replicas +- CDN for static assets + +## Next Steps + +- [Data Flow Diagrams](data-flow.md) +- [Future Architecture](future-architecture.md) + diff --git a/docs/contributing/development.md b/docs/contributing/development.md new file mode 100644 index 0000000..8765ada --- /dev/null +++ b/docs/contributing/development.md @@ -0,0 +1,79 @@ +# Development Setup + +Set up your development environment for ChatOps. + +## Prerequisites + +- Python 3.12+ +- Node.js 18+ +- Go 1.24+ +- PostgreSQL 16+ +- Docker (optional) + +## Backend Setup + +```bash +cd api +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +pip install -r requirements.txt + +# Create .env file +cp .env.example .env +# Edit .env with your configuration + +# Run migrations +alembic upgrade head + +# Start server +uvicorn app.main:app --reload +``` + +## Frontend Setup + +```bash +cd web +npm install + +# Create .env file +cp .env.example .env +# Edit .env with your API URL + +# Start dev server +npm run dev +``` + +## Agent Setup + +```bash +cd agent +go build -o chatops-agent ./main.go +./chatops-agent -api-key YOUR_KEY -api-url http://localhost:8000 +``` + +## Running Tests + +### Backend + +```bash +cd api +pytest +``` + +### Frontend + +```bash +cd web +npm test +``` + +## Code Style + +- **Python**: PEP 8, use `black` for formatting +- **TypeScript**: ESLint rules +- **Go**: `gofmt` + +## Next Steps + +- [Testing Guide](testing.md) + diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 0000000..8f0b7a4 --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,44 @@ +# Contributing + +Thank you for your interest in contributing to ChatOps! + +## Getting Started + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Submit a pull request + +## Development Setup + +See [Development Setup Guide](development.md) for: +- Setting up the development environment +- Running tests +- Code style guidelines + +## Testing + +See [Testing Guide](testing.md) for: +- Running tests +- Writing new tests +- Test coverage + +## Code Style + +- **Python**: Follow PEP 8 +- **TypeScript**: Follow ESLint rules +- **Go**: Follow `gofmt` style + +## Pull Request Process + +1. Update documentation if needed +2. Add tests for new features +3. Ensure all tests pass +4. Update CHANGELOG.md +5. Submit PR with clear description + +## Next Steps + +- [Development Setup](development.md) +- [Testing Guide](testing.md) + diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md new file mode 100644 index 0000000..59a9f51 --- /dev/null +++ b/docs/contributing/testing.md @@ -0,0 +1,48 @@ +# Testing Guide + +Testing guidelines for ChatOps. + +## Backend Tests + +### Running Tests + +```bash +cd api +pytest +``` + +### Test Structure + +- `tests/` - Test files +- `conftest.py` - Pytest configuration and fixtures +- `test_*.py` - Test modules + +### Writing Tests + +```python +def test_example(client: TestClient): + """Test example endpoint.""" + response = client.get("/api/v1/example") + assert response.status_code == 200 +``` + +## Frontend Tests + +### Running Tests + +```bash +cd web +npm test +``` + +## Test Coverage + +- Aim for >80% coverage +- Test critical paths +- Test error cases +- Test edge cases + +## Next Steps + +- [Development Setup](development.md) + diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md new file mode 100644 index 0000000..6e30f08 --- /dev/null +++ b/docs/deployment/docker.md @@ -0,0 +1,59 @@ +# Docker Deployment + +Deploy ChatOps using Docker and Docker Compose. + +## Quick Start + +```bash +# Clone repository +git clone https://github.com/martian56/chatops.git +cd chatops + +# Create .env file +cat > api/.env << EOF +DATABASE_URL=postgresql://user:password@db:5432/chatops +SECRET_KEY=your-secret-key-change-in-production +CORS_ORIGINS=["http://localhost:5173"] +EOF + +# Start services +docker compose up -d --build +``` + +## Services + +### API Service + +- **Image**: Built from `api/Dockerfile` +- **Port**: 8000 +- **Environment**: See `api/.env` +- **Dependencies**: Database service + +### Database Service + +- **Image**: `postgres:16-alpine` +- **Port**: 5432 +- **Volume**: `postgres_data` + +## Dockerfile Details + +The API Dockerfile: + +- Uses Python 3.12-slim base image +- Runs as non-root user (`appuser`) +- Installs dependencies +- Runs Alembic migrations on startup +- Exposes port 8000 + +## Environment Variables + +See `docker-compose.yml` for environment variable configuration. + +## Volumes + +- `postgres_data`: PostgreSQL data persistence + +## Next Steps + +- [Production Deployment](production.md) + diff --git a/docs/deployment/index.md b/docs/deployment/index.md new file mode 100644 index 0000000..ff0845a --- /dev/null +++ b/docs/deployment/index.md @@ -0,0 +1,48 @@ +# Deployment Guide + +Deployment guides for ChatOps in various environments. + +## Deployment Options + +1. **Docker Compose**: Quick setup for development and small deployments +2. **Production**: Manual deployment with best practices +3. **Cloud**: Deploy to cloud platforms (AWS, GCP, Azure) + +## Quick Start with Docker + +```bash +# Clone repository +git clone https://github.com/martian56/chatops.git +cd chatops + +# Configure environment +cat > api/.env << EOF +DATABASE_URL=postgresql://user:password@db:5432/chatops +SECRET_KEY=your-secret-key-change-in-production +CORS_ORIGINS=["http://localhost:5173"] +EOF + +# Start services +docker compose up -d --build +``` + +## Production Deployment + +See [Production Deployment Guide](production.md) for: +- Security best practices +- Performance optimization +- Monitoring and logging +- Backup strategies + +## Docker Deployment + +See [Docker Deployment Guide](docker.md) for: +- Dockerfile details +- Docker Compose configuration +- Container orchestration + +## Next Steps + +- [Docker Guide](docker.md) +- [Production Guide](production.md) + diff --git a/docs/deployment/production.md b/docs/deployment/production.md new file mode 100644 index 0000000..c4ae13c --- /dev/null +++ b/docs/deployment/production.md @@ -0,0 +1,67 @@ +# Production Deployment + +Best practices for deploying ChatOps in production. + +## Prerequisites + +- Production server(s) +- PostgreSQL database +- Domain name with SSL certificate +- Reverse proxy (Nginx, Traefik, etc.) + +## Security + +### Environment Variables + +- Use strong `SECRET_KEY` +- Use secure database credentials +- Configure CORS origins properly +- Use HTTPS in production + +### Database + +- Use strong database passwords +- Enable SSL connections +- Regular backups +- Monitor database performance + +### API + +- Run behind reverse proxy +- Enable rate limiting +- Use HTTPS +- Monitor logs + +## Performance + +### Database + +- Use connection pooling +- Optimize queries +- Add indexes where needed +- Monitor slow queries + +### API + +- Use async operations +- Enable caching (future: Redis) +- Monitor response times +- Scale horizontally (future) + +## Monitoring + +- Application logs +- Database metrics +- Server metrics +- Error tracking + +## Backup Strategy + +- Database backups (daily) +- Configuration backups +- Test restore procedures + +## Next Steps + +- [Docker Deployment](docker.md) + diff --git a/docs/frontend/index.md b/docs/frontend/index.md new file mode 100644 index 0000000..81116e4 --- /dev/null +++ b/docs/frontend/index.md @@ -0,0 +1,41 @@ +# Frontend Documentation + +React-based frontend for ChatOps. + +## Overview + +The ChatOps frontend is built with React 18 and TypeScript, providing a modern, responsive user interface. + +## Features + +- Real-time dashboard with live metrics +- Docker container management +- Alert configuration and monitoring +- Web terminal for command execution +- Server management interface +- JWT authentication + +## Tech Stack + +- React 18 +- TypeScript +- Vite +- TanStack Query +- Zustand +- Tailwind CSS +- Shadcn UI +- Recharts + +## Getting Started + +See [Setup Guide](setup.md) for installation and development instructions. + +## Architecture + +See [Architecture Guide](architecture.md) for frontend architecture details. + +## Next Steps + +- [Setup Guide](setup.md) +- [Architecture Guide](architecture.md) + diff --git a/docs/frontend/setup.md b/docs/frontend/setup.md new file mode 100644 index 0000000..524a2b9 --- /dev/null +++ b/docs/frontend/setup.md @@ -0,0 +1,42 @@ +# Frontend Setup + +Setup guide for the ChatOps frontend. + +## Prerequisites + +- Node.js 18+ +- npm or yarn + +## Installation + +```bash +cd web +npm install +``` + +## Configuration + +Create `.env` file: + +```env +VITE_API_URL=http://localhost:8000 +``` + +## Development + +```bash +npm run dev +``` + +The app will be available at `http://localhost:5173` + +## Build + +```bash +npm run build +``` + +## Next Steps + +- [Architecture Guide](architecture.md) + diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..1643e48 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,33 @@ +# Getting Started + +Welcome to ChatOps! This guide will help you get started with the platform. + +## What You'll Learn + +- Understanding ChatOps capabilities +- Setting up your first server +- Installing and configuring agents +- Using the web dashboard + +## Prerequisites + +- A ChatOps instance (self-hosted or cloud) +- Access to servers you want to monitor +- Basic knowledge of Linux/Unix systems + +## Quick Start + +1. **Create an Account**: Register in the ChatOps web interface +2. **Add a Server**: Create a server entry in the dashboard +3. **Generate API Key**: Create an API key for your server +4. **Install Agent**: Deploy the agent on your server +5. **Start Monitoring**: View real-time metrics in the dashboard + +For detailed instructions, see the [Quick Start Guide](quick-start.md). + +## Next Steps + +- [Quick Start Guide](quick-start.md) - Step-by-step setup instructions +- [Installation Guide](installation.md) - Detailed installation instructions +- [Agent Installation](../agent/installation.md) - Deploy agents on your servers + diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..78e9e01 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,202 @@ +# Installation Guide + +Complete installation guide for ChatOps components. + +## Overview + +ChatOps consists of three main components: + +1. **Web Frontend** - React-based user interface +2. **API Backend** - FastAPI server +3. **Agent** - Go binary for server monitoring + +## Prerequisites + +### For Backend/API + +- Python 3.12+ +- PostgreSQL 16+ +- Docker (optional, for containerized deployment) + +### For Frontend + +- Node.js 18+ +- npm or yarn + +### For Agent + +- Linux/Unix system +- Docker (optional, for container management features) + +## Backend Installation + +### Option 1: Docker (Recommended) + +```bash +# Clone the repository +git clone https://github.com/martian56/chatops.git +cd chatops + +# Create .env file +cat > api/.env << EOF +DATABASE_URL=postgresql://user:password@db:5432/chatops +SECRET_KEY=your-secret-key-change-in-production +CORS_ORIGINS=["http://localhost:5173"] +EOF + +# Start services +docker compose up -d --build + +# The API will be available at http://localhost:8000 +``` + +### Option 2: Manual Installation + +```bash +# Create virtual environment +cd api +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt + +# Create .env file +cat > .env << EOF +DATABASE_URL=postgresql://user:password@localhost/chatops +SECRET_KEY=your-secret-key-change-in-production +CORS_ORIGINS=["http://localhost:5173"] +EOF + +# Run database migrations +alembic upgrade head + +# Start the server +uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 +``` + +## Frontend Installation + +```bash +# Navigate to web directory +cd web + +# Install dependencies +npm install + +# Create .env file +cat > .env << EOF +VITE_API_URL=http://localhost:8000 +EOF + +# Development server +npm run dev + +# Production build +npm run build +``` + +## Agent Installation + +See the [Agent Installation Guide](../agent/installation.md) for detailed instructions. + +## Database Setup + +### PostgreSQL Installation + +```bash +# Ubuntu/Debian +sudo apt-get update +sudo apt-get install postgresql-16 + +# macOS (Homebrew) +brew install postgresql@16 +brew services start postgresql@16 + +# Create database +sudo -u postgres psql +CREATE DATABASE chatops; +CREATE USER chatops_user WITH PASSWORD 'your_password'; +GRANT ALL PRIVILEGES ON DATABASE chatops TO chatops_user; +\q +``` + +### Run Migrations + +```bash +cd api +alembic upgrade head +``` + +## Environment Variables + +### Backend (.env) + +```env +# Database +DATABASE_URL=postgresql://user:password@localhost/chatops + +# Security +SECRET_KEY=your-secret-key-change-in-production +ALGORITHM=HS256 +ACCESS_TOKEN_EXPIRE_MINUTES=30 +REFRESH_TOKEN_EXPIRE_DAYS=7 + +# CORS +CORS_ORIGINS=["http://localhost:5173", "http://localhost:3000"] +``` + +### Frontend (.env) + +```env +VITE_API_URL=http://localhost:8000 +``` + +## Verification + +### Backend + +```bash +# Health check +curl http://localhost:8000/health + +# API docs +open http://localhost:8000/docs +``` + +### Frontend + +```bash +# Open in browser +open http://localhost:5173 +``` + +## Production Deployment + +For production deployment, see the [Production Deployment Guide](../deployment/production.md). + +## Troubleshooting + +### Database Connection Issues + +- Verify PostgreSQL is running +- Check DATABASE_URL format +- Ensure database and user exist + +### Port Conflicts + +- Change API port: `--port 8001` +- Change frontend port: Update `vite.config.ts` + +### Migration Errors + +- Check database connection +- Verify Alembic configuration +- Review migration files + +## Next Steps + +- [Quick Start Guide](quick-start.md) +- [Production Deployment](../deployment/production.md) +- [Configuration Guide](../agent/configuration.md) + diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..7edd7f8 --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,123 @@ +# Quick Start Guide + +Get up and running with ChatOps in minutes! + +## Step 1: Access the Web Interface + +1. Navigate to your ChatOps instance URL +2. Click **"Register"** to create a new account +3. Fill in your details: + - Email address + - Username + - Password (minimum 8 characters) + - Full name +4. Click **"Create Account"** + +## Step 2: Add Your First Server + +1. After logging in, navigate to **"Servers"** from the sidebar +2. Click **"Add Server"** button +3. Fill in the server details: + - **Name**: A descriptive name (e.g., "Production Web Server") + - **Host**: IP address or hostname (optional, for reference) + - **Port**: SSH port (optional, for reference) +4. Click **"Create"** + +## Step 3: Generate an API Key + +1. Click on your newly created server +2. Navigate to the **"API Keys"** tab +3. Click **"Create API Key"** +4. Optionally give it a name (e.g., "Main Agent") +5. **⚠️ IMPORTANT**: Copy the API key immediately - it's only shown once! + +## Step 4: Install the Agent + +### Option A: Debian/Ubuntu Package (Recommended) + +```bash +# Download the .deb package +wget https://github.com/martian56/chatops/releases/download/v1.0.3/chatops-agent_1.0.3_amd64.deb + +# Install the package +sudo dpkg -i chatops-agent_1.0.3_amd64.deb +sudo apt-get install -f # Install dependencies if needed + +# Configure the API key +sudo systemctl edit chatops-agent.service +# Add: Environment="CHATOPS_API_KEY=your-api-key-here" + +# Start the service +sudo systemctl daemon-reload +sudo systemctl enable chatops-agent +sudo systemctl start chatops-agent + +# Check status +sudo systemctl status chatops-agent +``` + +### Option B: Binary Installation + +```bash +# Download the binary +wget https://github.com/martian56/chatops/releases/download/v1.0.3/chatops-agent-linux-amd64-1.0.3.tar.gz +tar -xzf chatops-agent-linux-amd64-1.0.3.tar.gz + +# Run the agent +./chatops-agent-linux-amd64 -api-key YOUR_API_KEY_HERE +``` + +### Option C: Environment Variables + +```bash +export CHATOPS_API_KEY="your-api-key-here" +export CHATOPS_API_URL="https://your-chatops-instance.com" # Optional +./chatops-agent +``` + +## Step 5: Verify Connection + +1. Return to the ChatOps web interface +2. Navigate to your server's detail page +3. You should see: + - Server status: **ONLINE** (green indicator) + - Real-time metrics appearing in the Metrics tab + - Docker containers listed (if Docker is installed) + +## What Happens Next? + +Once the agent is connected: + +- **Metrics**: System metrics (CPU, memory, disk, network) are collected every 5 seconds +- **Docker**: Container information is available for management +- **Logs**: System and application logs are accessible +- **Terminal**: Remote command execution is enabled + +## Troubleshooting + +### Agent Not Connecting + +- **Check API Key**: Verify the API key is correct and active +- **Check Network**: Ensure the server can reach the ChatOps API URL +- **Check Logs**: View agent logs for error messages + ```bash + sudo journalctl -u chatops-agent -f + ``` + +### No Metrics Appearing + +- **Wait a few seconds**: Metrics are sent every 5 seconds +- **Check Agent Status**: Verify the agent is running +- **Check Server Status**: Ensure the server shows as ONLINE + +### API Key Issues + +- **Invalid Key**: Generate a new API key if the current one is invalid +- **Inactive Key**: Check that the API key is active in the dashboard + +## Next Steps + +- [Detailed Installation Guide](installation.md) +- [Agent Configuration](../agent/configuration.md) +- [Using the Dashboard](../frontend/index.md) + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..515c709 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,80 @@ +# ChatOps Documentation + +Welcome to the ChatOps documentation! ChatOps is a comprehensive server monitoring and management platform that enables you to monitor, manage, and control your servers from a single, intuitive web dashboard. + +## What is ChatOps? + +ChatOps is a unified server monitoring and DevOps platform that provides: + +- **Real-time Monitoring**: Live metrics for CPU, memory, disk, and network usage +- **Docker Management**: Control containers with one-click actions +- **Alert System**: Configure and monitor performance thresholds +- **Remote Terminal**: Execute commands remotely via web terminal +- **Audit Logging**: Complete history of all system activity + +## Key Features + +### 🎯 Core Capabilities + +- **Multi-Server Management**: Monitor and manage multiple servers from one dashboard +- **Real-time Updates**: WebSocket-based live updates for metrics and logs +- **Secure Authentication**: JWT-based authentication with API key support +- **Docker Integration**: Full Docker container lifecycle management +- **Alert Management**: Configurable thresholds with automatic alerting +- **Command Execution**: Secure remote command execution with full logging + +### 🏗️ Architecture + +ChatOps follows a three-tier architecture: + +1. **Web Frontend** (React/TypeScript) - Modern, responsive UI +2. **API Backend** (FastAPI/Python) - RESTful API with WebSocket support +3. **Agent** (Go) - Lightweight agent deployed on monitored servers + +## Quick Navigation + +### For Users + +- [Getting Started](getting-started/index.md) - Start using ChatOps +- [Agent Installation](agent/installation.md) - Deploy agents on your servers +- [API Reference](api/index.md) - Integrate with the API + +### For Developers + +- [Architecture Overview](architecture/index.md) - Understand the system design +- [Development Setup](contributing/development.md) - Set up your development environment +- [API Documentation](api/rest-endpoints.md) - Detailed API reference + +### For DevOps + +- [Deployment Guide](deployment/index.md) - Deploy ChatOps in production +- [Docker Setup](deployment/docker.md) - Container-based deployment +- [Production Best Practices](deployment/production.md) - Production recommendations + +## Documentation Structure + +This documentation is organized into the following sections: + +- **[Getting Started](getting-started/index.md)**: Installation and quick start guides +- **[Architecture & Design](architecture/index.md)**: System architecture and design decisions +- **[API Reference](api/index.md)**: Complete API documentation +- **[Agent](agent/index.md)**: Agent installation and configuration +- **[Frontend](frontend/index.md)**: Frontend development guide +- **[Technologies](technologies/index.md)**: Technology stack overview +- **[Deployment](deployment/index.md)**: Deployment guides and best practices +- **[Contributing](contributing/index.md)**: Development and contribution guidelines + +## Getting Help + +- **GitHub Issues**: [Report bugs or request features](https://github.com/martian56/chatops/issues) +- **Documentation**: Browse the sections above for detailed information +- **API Docs**: Interactive API documentation at `/docs` endpoint when running the API + +## License + +This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. + +--- + +**Ready to get started?** Check out the [Quick Start Guide](getting-started/quick-start.md)! + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..bb9e6de --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +mkdocs==1.5.3 +mkdocs-material==9.5.3 +mkdocs-git-revision-date-localized-plugin==1.2.0 +pymdown-extensions==10.5 + diff --git a/docs/technologies/agent.md b/docs/technologies/agent.md new file mode 100644 index 0000000..b3dd9dd --- /dev/null +++ b/docs/technologies/agent.md @@ -0,0 +1,25 @@ +# Agent Technology Stack + +Technologies used in the ChatOps agent. + +## Language + +- **Go 1.24+**: Programming language + +## Libraries + +- **Docker Go Client**: Docker API integration +- **Gorilla WebSocket**: WebSocket client +- **gopsutil**: System metrics collection + +## Features + +- Single binary deployment +- Low resource usage +- Cross-platform support + +## Next Steps + +- [Backend Stack](backend.md) +- [Frontend Stack](frontend.md) + diff --git a/docs/technologies/backend.md b/docs/technologies/backend.md new file mode 100644 index 0000000..e0f5b71 --- /dev/null +++ b/docs/technologies/backend.md @@ -0,0 +1,35 @@ +# Backend Technology Stack + +Technologies used in the ChatOps backend. + +## Core Framework + +- **FastAPI**: Modern, fast web framework +- **Uvicorn**: ASGI server + +## Database + +- **PostgreSQL**: Relational database +- **SQLAlchemy**: Async ORM +- **asyncpg**: Async PostgreSQL driver +- **Alembic**: Database migrations + +## Authentication + +- **python-jose**: JWT token handling +- **passlib**: Password hashing +- **bcrypt**: Password hashing algorithm + +## Validation + +- **Pydantic V2**: Data validation and settings + +## WebSockets + +- **FastAPI WebSocket**: WebSocket support + +## Next Steps + +- [Frontend Stack](frontend.md) +- [Agent Stack](agent.md) + diff --git a/docs/technologies/frontend.md b/docs/technologies/frontend.md new file mode 100644 index 0000000..4d02a43 --- /dev/null +++ b/docs/technologies/frontend.md @@ -0,0 +1,37 @@ +# Frontend Technology Stack + +Technologies used in the ChatOps frontend. + +## Core + +- **React 18**: UI framework +- **TypeScript**: Type safety +- **Vite**: Build tool + +## State Management + +- **TanStack Query**: Server state +- **Zustand**: Client state + +## Routing + +- **React Router**: Client-side routing + +## Styling + +- **Tailwind CSS**: Utility-first CSS +- **Shadcn UI**: Component library + +## Data Visualization + +- **Recharts**: Chart library + +## HTTP Client + +- **Axios**: HTTP requests + +## Next Steps + +- [Backend Stack](backend.md) +- [Agent Stack](agent.md) + diff --git a/docs/technologies/index.md b/docs/technologies/index.md new file mode 100644 index 0000000..91d3c40 --- /dev/null +++ b/docs/technologies/index.md @@ -0,0 +1,64 @@ +# Technology Stack + +Overview of technologies used in ChatOps. + +## Backend + +- **FastAPI**: Modern, fast web framework for Python +- **SQLAlchemy**: Async ORM for database operations +- **PostgreSQL**: Relational database +- **asyncpg**: Async PostgreSQL driver +- **Pydantic**: Data validation and settings +- **Alembic**: Database migrations +- **JWT**: Authentication tokens +- **WebSockets**: Real-time communication + +## Frontend + +- **React 18**: UI framework +- **TypeScript**: Type safety +- **Vite**: Build tool and dev server +- **TanStack Query**: Server state management +- **Zustand**: Client state management +- **React Router**: Client-side routing +- **Tailwind CSS**: Utility-first CSS +- **Shadcn UI**: Component library +- **Recharts**: Data visualization +- **Axios**: HTTP client + +## Agent + +- **Go 1.24+**: Programming language +- **Docker Go Client**: Docker API integration +- **Gorilla WebSocket**: WebSocket client +- **gopsutil**: System metrics collection + +## Infrastructure + +- **Docker**: Containerization +- **Docker Compose**: Multi-container orchestration +- **PostgreSQL**: Database +- **GitHub Actions**: CI/CD + +## Development Tools + +- **Pytest**: Python testing +- **ESLint**: JavaScript linting +- **TypeScript**: Type checking +- **Alembic**: Database migrations + +## Future Technologies + +- **Kafka**: Event streaming +- **Redis**: Caching and pub/sub +- **TimescaleDB**: Time-series database +- **Kubernetes**: Container orchestration +- **Prometheus**: Metrics collection +- **Grafana**: Visualization + +## Next Steps + +- [Backend Stack](backend.md) +- [Frontend Stack](frontend.md) +- [Agent Stack](agent.md) + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f901ec3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,113 @@ +site_name: ChatOps Documentation +site_description: Comprehensive documentation for the ChatOps server monitoring and management platform +site_author: ChatOps Team +site_url: https://chatops-docs.pages.dev + +# Standard MkDocs structure: config in root, docs in docs/ directory +docs_dir: docs + +repo_name: martian56/chatops +repo_url: https://github.com/martian56/chatops +edit_uri: edit/main/docs/ + +theme: + name: material + palette: + - scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + icon: + repo: fontawesome/brands/github + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - admonition + - pymdownx.details + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +nav: + - Home: index.md + - Getting Started: + - Overview: getting-started/index.md + - Quick Start: getting-started/quick-start.md + - Installation: getting-started/installation.md + - Architecture & Design: + - Overview: architecture/index.md + - System Architecture: architecture/system-architecture.md + - Data Flow: architecture/data-flow.md + - Future Architecture: architecture/future-architecture.md + - API Reference: + - Overview: api/index.md + - Authentication: api/authentication.md + - REST Endpoints: api/rest-endpoints.md + - WebSocket API: api/websocket-api.md + - API Keys: api/api-keys.md + - Agent: + - Overview: agent/index.md + - Installation: agent/installation.md + - Configuration: agent/configuration.md + - Development: agent/development.md + - Frontend: + - Overview: frontend/index.md + - Setup: frontend/setup.md + - Architecture: frontend/architecture.md + - Technologies: + - Overview: technologies/index.md + - Backend Stack: technologies/backend.md + - Frontend Stack: technologies/frontend.md + - Agent Stack: technologies/agent.md + - Deployment: + - Overview: deployment/index.md + - Docker: deployment/docker.md + - Production: deployment/production.md + - Contributing: + - Overview: contributing/index.md + - Development Setup: contributing/development.md + - Testing: contributing/testing.md + +plugins: + - search + - git-revision-date-localized: + enable_creation_date: true + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/martian56/chatops + version: + provider: mike +