docs: Add documentation for FlatRun UI

docs.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/whilesmart/docs-kit/main/schema/docs.schema.json",
+  "name": "FlatRun UI",
+  "description": "Modern Vue 3 web interface for FlatRun container orchestration with real-time monitoring and deployment management",
+  "icon": "layout-dashboard",
+  "category": {
+    "language": "typescript",
+    "framework": "vue"
+  },
+  "sidebar": [
+    { "title": "Overview", "path": "docs/overview.md" },
+    { "title": "Development", "path": "docs/development.md" },
+    { "title": "Connecting to Agent", "path": "docs/connecting-to-agent.md" },
+    { "title": "Production Deployment", "path": "docs/deployment.md" }
+  ]
+}

docs/connecting-to-agent.md

@@ -0,0 +1,35 @@
+## Connecting to FlatRun Agent
+
+The UI requires a running FlatRun Agent instance. See the [FlatRun Agent documentation](https://github.com/flatrun/agent) for installation instructions.
+
+### Environment Configuration
+
+Create a `.env.local` file:
+
+```bash
+# FlatRun Agent API URL
+VITE_API_URL=http://localhost:8090
+```
+
+For production:
+
+```bash
+VITE_API_URL=https://your-server.com/api
+```
+
+### Authentication
+
+The UI uses the API key configured in the agent's `config.yml`. Enter the key when prompted by the login form.
+
+### CORS Configuration
+
+If the UI runs on a different domain or port than the agent, ensure the agent's CORS settings include your UI URL:
+
+```yaml
+# In agent's config.yml
+api:
+  enable_cors: true
+  allowed_origins:
+    - http://localhost:5173
+    - https://your-ui-domain.com
+```

docs/deployment.md

@@ -0,0 +1,55 @@
+## Production Deployment
+
+### Build
+
+```bash
+npm run build
+```
+
+This creates a `dist/` directory with optimized static files.
+
+### Serving with Nginx
+
+```nginx
+server {
+    listen 80;
+    server_name flatrun.example.com;
+    root /var/www/flatrun-ui/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api {
+        proxy_pass http://localhost:8090;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+### Docker Deployment
+
+```dockerfile
+FROM nginx:alpine
+COPY dist/ /usr/share/nginx/html/
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+```
+
+### Troubleshooting
+
+**Cannot connect to agent:**
+- Verify the agent is running: `systemctl status flatrun-agent`
+- Check `VITE_API_URL` is correct in `.env.local`
+- Ensure CORS is configured if running on different domains
+
+**Authentication fails:**
+- Verify the API key matches the agent's configuration
+- Check the browser console for specific error messages
+- Ensure the JWT secret is properly set in the agent config
+
+**UI shows no deployments:**
+- Confirm the agent's `deployments_path` is accessible
+- Check that deployments have valid `docker-compose.yml` files

docs/development.md

@@ -0,0 +1,43 @@
+## Development
+
+### Prerequisites
+
+- Node.js 18 or later and npm
+
+### Setup
+
+```bash
+npm install
+npm run dev
+```
+
+The development server starts at `http://localhost:5173`.
+
+### Project Structure
+
+```
+ui/
+├── src/
+│   ├── assets/          Static assets and global styles
+│   ├── components/      Reusable Vue components (DataTable, etc.)
+│   ├── layouts/         Page layouts (DashboardLayout)
+│   ├── views/           Page components (HomeView, DeploymentsView, etc.)
+│   ├── stores/          Pinia stores (auth, deployments)
+│   ├── router/          Vue Router configuration
+│   ├── services/        API client services (axios instances)
+│   ├── types/           TypeScript type definitions
+│   ├── App.vue          Root component
+│   └── main.ts          Application entry point
+├── public/              Public static files
+└── index.html           HTML entry point
+```
+
+### Available Scripts
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start development server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build locally |
+| `npm run lint` | Run ESLint |
+| `npm run format` | Format code with Prettier |

docs/overview.md

@@ -0,0 +1,24 @@
+## Overview
+
+FlatRun UI provides a user-friendly dashboard for managing Docker deployments through the FlatRun Agent. It offers real-time monitoring, container management, and a streamlined deployment workflow.
+
+### Features
+
+- **Deployment Management** - Create, start, stop, and delete Docker Compose deployments
+- **Container Monitoring** - Real-time status, resource usage, and health checks
+- **Log Viewer** - Live streaming logs with search and filtering
+- **Docker Resource Management** - Images, volumes, and networks overview
+- **SSL Certificate Tracking** - Monitor certificate expiration and status
+- **Quick App Templates** - Deploy common applications with pre-configured templates
+- **System Health Dashboard** - CPU, memory, and disk usage monitoring
+- **JWT Authentication** - Secure API key-based authentication
+
+### Tech Stack
+
+- **Framework:** Vue 3 with Composition API
+- **Language:** TypeScript
+- **Build Tool:** Vite
+- **State Management:** Pinia
+- **Routing:** Vue Router
+- **UI Components:** PrimeVue
+- **HTTP Client:** Axios