docs: Add documentation for FlatRun Agent

docs.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/whilesmart/docs-kit/main/schema/docs.schema.json",
+  "name": "FlatRun Agent",
+  "description": "Lightweight Go backend for flat-file Docker Compose orchestration with a REST API, container lifecycle management, and plugin architecture",
+  "icon": "server",
+  "category": {
+    "language": "go",
+    "framework": "app"
+  },
+  "sidebar": [
+    { "title": "Overview", "path": "docs/overview.md" },
+    { "title": "Installation", "path": "docs/installation.md" },
+    { "title": "Configuration", "path": "docs/configuration.md" },
+    { "title": "API Reference", "path": "docs/api-reference.md" },
+    { "title": "Plugin Architecture", "path": "docs/PLUGIN_ARCHITECTURE.md" },
+    { "title": "Security", "path": "docs/security.md" }
+  ]
+}

docs/api-reference.md

@@ -0,0 +1,43 @@
+## API Reference
+
+### Authentication
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/api/auth/login` | Login with API key |
+| GET | `/api/auth/validate` | Validate JWT token |
+| GET | `/api/auth/status` | Check auth status |
+
+### Deployments
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/deployments` | List all deployments |
+| POST | `/api/deployments` | Create new deployment |
+| GET | `/api/deployments/:name` | Get deployment details |
+| DELETE | `/api/deployments/:name` | Delete deployment |
+| POST | `/api/deployments/:name/start` | Start deployment |
+| POST | `/api/deployments/:name/stop` | Stop deployment |
+| POST | `/api/deployments/:name/restart` | Restart deployment |
+| GET | `/api/deployments/:name/logs` | Get deployment logs |
+
+### Docker Resources
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/containers` | List containers |
+| GET | `/api/images` | List images |
+| GET | `/api/volumes` | List volumes |
+| GET | `/api/networks` | List networks |
+| POST | `/api/networks` | Create network |
+| DELETE | `/api/networks/:name` | Delete network |
+
+### Other
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/health` | Health check |
+| GET | `/api/stats` | System statistics |
+| GET | `/api/certificates` | List SSL certificates |
+| GET | `/api/templates` | List Quick App templates |
+| GET | `/api/plugins` | List installed plugins |

docs/configuration.md

@@ -0,0 +1,57 @@
+## Configuration
+
+Copy the example configuration and edit it:
+
+```bash
+cp config.example.yml config.yml
+```
+
+### Reference
+
+```yaml
+deployments_path: /home/user/deployments
+docker_socket: unix:///var/run/docker.sock
+
+api:
+  host: 0.0.0.0
+  port: 8090
+  enable_cors: true
+  allowed_origins:
+    - http://localhost:5173
+    - http://localhost:3000
+
+auth:
+  enabled: true
+  api_keys:
+    - "your-secure-api-key-here"
+  jwt_secret: "generate-a-secure-random-string-here"
+
+nginx:
+  container_name: nginx
+  config_path: /deployments/nginx/conf.d
+  reload_command: nginx -s reload
+
+certbot:
+  container_name: certbot
+  email: your-email@example.com
+  staging: true
+
+logging:
+  level: info
+  format: json
+
+health:
+  check_interval: 30s
+  metrics_retention: 24h
+```
+
+### Key Options
+
+| Option | Description |
+|---|---|
+| `deployments_path` | Directory containing docker-compose deployments |
+| `api.port` | API server port (default: 8090) |
+| `auth.api_keys` | Valid API keys for authentication |
+| `auth.jwt_secret` | Secret for signing JWT tokens |
+| `logging.level` | Log level: debug, info, warn, error |
+| `health.check_interval` | Health check frequency |

docs/installation.md

@@ -0,0 +1,81 @@
+## Installation
+
+### Prerequisites
+
+- Go 1.21 or later (for building from source)
+- Docker and Docker Compose v2
+- Access to Docker socket (`/var/run/docker.sock`)
+- Linux server (Ubuntu 20.04+, Debian 11+, or similar)
+
+### Option 1: Build from Source
+
+```bash
+git clone https://github.com/flatrun/agent.git
+cd agent
+make build
+```
+
+Or manually:
+
+```bash
+go mod download
+go build -o flatrun-agent ./cmd/agent
+```
+
+### Option 2: Download Binary
+
+```bash
+wget https://github.com/flatrun/agent/releases/latest/download/flatrun-agent
+chmod +x flatrun-agent
+```
+
+### Running
+
+Development mode:
+
+```bash
+make run
+# or
+./flatrun-agent --config config.yml
+```
+
+### Production with Systemd
+
+Move the binary to a system location:
+
+```bash
+sudo mv flatrun-agent /usr/local/bin/
+sudo chmod +x /usr/local/bin/flatrun-agent
+```
+
+Create `/etc/systemd/system/flatrun-agent.service`:
+
+```ini
+[Unit]
+Description=FlatRun Agent
+After=network.target docker.service
+Requires=docker.service
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/flatrun
+ExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable flatrun-agent
+sudo systemctl start flatrun-agent
+sudo systemctl status flatrun-agent
+sudo journalctl -u flatrun-agent -f
+```

docs/overview.md

@@ -0,0 +1,19 @@
+## Overview
+
+FlatRun Agent is the backend service that manages Docker deployments through a simple filesystem-based approach. It monitors your deployments directory and provides a REST API for the FlatRun UI.
+
+### Features
+
+- Docker Compose deployment management
+- Container lifecycle control (start, stop, restart)
+- Real-time container monitoring and logs
+- Docker resource management (images, volumes, networks)
+- SSL certificate monitoring
+- Quick App templates for rapid deployment
+- JWT-based API authentication
+- Health monitoring and statistics
+- Plugin architecture for extensibility
+
+### Architecture
+
+The agent follows a flat-file approach: each deployment is a directory containing a `docker-compose.yml` file. The agent watches the configured deployments directory and manages the containers through the Docker API. It communicates with the FlatRun UI through a REST API and uses JWT tokens for authentication.

docs/security.md

@@ -0,0 +1,23 @@
+## Security
+
+- Use strong, unique API keys.
+- Generate a secure JWT secret: `openssl rand -base64 32`.
+- Run behind a reverse proxy (nginx) with HTTPS in production.
+- Restrict Docker socket access appropriately.
+- Keep the agent updated.
+
+### Troubleshooting
+
+**Agent won't start:**
+- Check Docker is running: `systemctl status docker`
+- Verify Docker socket permissions: `ls -la /var/run/docker.sock`
+- Validate the config YAML syntax
+
+**Authentication issues:**
+- Ensure the API key matches between UI and agent config
+- Verify JWT secret is set
+- Check CORS origins include your UI URL
+
+**Can't see deployments:**
+- Verify `deployments_path` exists and is readable
+- Check each deployment has a valid `docker-compose.yml`