Frontend Application"] + end + + subgraph "Backend Services" + API["api
Backend API"] + DN["docknode
Remote Agent"] + end + + subgraph "Ecosystem" + DST["dockstore
Plugin Registry"] + DOCS["docs
Documentation"] + end + + subgraph "External" + DOCKER["Docker Daemons"] + BROWSER["Web Browser"] + end + + BROWSER --> DS + DS -->|"Eden Client"| API + API --> DOCKER + API --> DN + DN --> DOCKER + DST -->|"Plugin Bundles"| API + DOCS -->|"Outline Sync"| WIKI["Wiki"] +``` + +## Application Summary + +| Application | Type | Port | Purpose | +|----|----|----|----| +| `dockstat` | Frontend | 5173 (dev) / 3000 (prod) | Main user interface | +| `api` | Backend | 3000 | REST API and Docker management | +| `docknode` | Agent | 4000 | Remote Docker host management | +| `dockstore` | Registry | — | Plugin and template repository | +| `docs` | Documentation | — | Documentation and wiki sync | + +## dockstat (Frontend) + +### Overview + +The main DockStat frontend application built with React Router v7 for server-side rendering. Provides the user interface for container monitoring, management, and configuration. + +```mermaidjs + +graph TB + subgraph "Frontend Architecture" + ENTRY["entry.server.tsx"] + ROOT["root.tsx"] + ROUTES["routes/"] + API_CLIENT["api.ts (Eden)"] + end + + subgraph "Key Features" + MONITOR["Container Monitoring"] + MANAGE["Container Management"] + THEMES["Theme System"] + PLUGINS["Plugin UI"] + end + + subgraph "Technologies" + RR["React Router v7"] + TW["TailwindCSS"] + TS["TypeScript"] + BUN["Bun Runtime"] + end + + ENTRY --> ROOT + ROOT --> ROUTES + ROUTES --> API_CLIENT + API_CLIENT -->|"HTTP"| BACKEND["Backend API"] +``` + +### Directory Structure + +``` +apps/dockstat/ +├── app/ +│ ├── .server/ # Server-side utilities +│ ├── routes/ # React Router routes +│ ├── api.ts # Eden API client +│ ├── app.css # Global styles +│ ├── entry.client.tsx # Client entry point +│ ├── entry.server.tsx # Server entry point +│ ├── root.tsx # Root component +│ └── routes.ts # Route definitions +├── public/ # Static assets +├── build/ # Production build output +├── Dockerfile # Production container +├── react-router.config.ts +├── vite.config.ts +└── package.json +``` + +### Configuration + +```typescript +// react-router.config.ts + +import type { Config } from "@react-router/dev/config"; + +export default { + ssr: true, + future: { + // Enable future flags + } +} satisfies Config; +``` + +### Development + +```bash +cd apps/dockstat + +bun install + +bun run dev +# Available at http://localhost:5173 +``` + +### Production Build + +```bash +bun run build + +bun run start +# Available at http://localhost:3000 +``` + +### Key Features + +* **Server-Side Rendering**: Fast initial page loads with SSR +* **Type-Safe API Calls**: Eden client provides full type safety +* **Theme Support**: CSS variable-based theming system +* **Responsive Design**: TailwindCSS for responsive layouts +* **Hot Module Replacement**: Fast development iteration + + +--- + +## api (Backend) + +### Overview + +The DockStat backend API built with Elysia framework. Handles all Docker operations, plugin management, and data persistence. + +```mermaidjs + +graph TB + subgraph "API Architecture" + ENTRY["index.ts"] + PLUGINS["elysia-plugins.ts"] + ROUTES["routes/"] + HANDLERS["handlers/"] + end + + subgraph "Core Services" + DCM["DockerClientManager"] + PH["PluginHandler"] + DB["Database Layer"] + end + + subgraph "Route Groups" + DOCKER["/docker"] + PLUGIN["/plugins"] + METRICS["/metrics"] + CONFIG["/db"] + end + + ENTRY --> PLUGINS + ENTRY --> ROUTES + ROUTES --> DOCKER + ROUTES --> PLUGIN + ROUTES --> METRICS + ROUTES --> CONFIG + DOCKER --> DCM + PLUGIN --> PH + CONFIG --> DB +``` + +### Directory Structure + +``` +apps/api/ +├── src/ +│ ├── database/ # Database initialization +│ ├── docker/ # Docker client setup +│ ├── handlers/ # Request handlers +│ ├── middleware/ # Elysia middleware +│ ├── models/ # Typebox schemas +│ ├── plugins/ # Default plugins +│ ├── routes/ +│ │ ├── docker/ # Docker routes +│ │ ├── metrics/ # Prometheus metrics +│ │ └── plugins/ # Plugin routes +│ ├── utiles/ # Utility functions +│ ├── elysia-plugins.ts # Elysia plugin configuration +│ ├── index.ts # Main entry point +│ └── logger.ts # Logger setup +└── package.json +``` + +### Route Prefix + +All API routes are prefixed with `/api/v2`: + +| Route Group | Prefix | Purpose | +|----|----|----| +| Docker | `/api/v2/docker` | Container and host management | +| Plugins | `/api/v2/plugins` | Plugin administration | +| Metrics | `/api/v2/metrics` | Prometheus metrics endpoint | +| Database | `/api/v2/db` | Configuration management | + +### Configuration + +Environment variables: + +```bash +DOCKSTAT_MAX_WORKERS=200 # Max worker threads +DOCKSTATAPI_SHOW_TRACES=true # Enable server timing +DOCKSTATAPI_PORT=9876 # API port +``` + +### Development + +```bash +cd apps/api + +bun install + +bun run dev +# Available at http://localhost:9876 +``` + +### API Documentation + +OpenAPI documentation is available at `/api/v2/docs` using Scalar provider. + + +--- + +## docknode (Remote Agent) + +### Overview + +DockNode is a remote agent for managing Docker hosts that aren't directly accessible from the main DockStat instance. It provides secure stack deployment and management capabilities. + +```mermaidjs + +graph TB + subgraph "DockNode Architecture" + ENTRY["index.ts"] + DOCKSTACK["DockStackHandler"] + AUTH["Authentication"] + BUILDER["Stack Builder"] + end + + subgraph "Capabilities" + DEPLOY["Stack Deployment"] + DELETE["Stack Deletion"] + STATUS["Status Reporting"] + end + + subgraph "Security" + PSK["Pre-Shared Key"] + DEV["Dev Auth"] + end + + ENTRY --> DOCKSTACK + DOCKSTACK --> AUTH + DOCKSTACK --> BUILDER + AUTH --> PSK + AUTH --> DEV + BUILDER --> DEPLOY + BUILDER --> DELETE +``` + +### Directory Structure + +``` +apps/docknode/ +├── src/ +│ ├── handlers/ +│ │ ├── auth/ # Authentication handlers +│ │ └── dockstack/ # Stack management +│ ├── tests/ # Test files +│ ├── builder.ts # Docker Compose builder +│ └── index.ts # Main entry point +├── environment.d.ts # Type definitions +├── dockerfile # Production container +└── package.json +``` + +### API Endpoints + +| Method | Endpoint | Description | +|----|----|----| +| GET | `/api/status` | Health check | +| POST | `/api/dockstack/deploy` | Deploy a Docker Compose stack | +| DELETE | `/api/dockstack/delete` | Delete a deployed stack | +| GET | `/api/docs` | OpenAPI documentation | + +### Stack Deployment + +```typescript +// Deploy request body +{ + "id": 1, + "name": "my-stack", + "data": "version: '3.8'\nservices:\n ...", + "vars": { + "DOMAIN": "example.com", + "PORT": "8080" + } +} +``` + +### Authentication + +DockNode supports multiple authentication methods: + + +1. **Pre-Shared Key (PSK)**: For production environments +2. **Dev Auth**: For development and testing + +```bash +# Production + +DOCKNODE_DOCKSTACK_AUTH_PSK=
=> `docker compose up` | -| POST | `/stacks/stop` | Puts a Stack down
=> `docker compose down` | -| POST | `/stacks/restart` | Restarts a Stack=> `docker compose restart` | -| POST | `/stacks/pull-images` | Pulls all images for a Stack=> `docker compose pull` | -| GET | `/stacks/status` | Gets custom Stack status=> Adjusted: `docker compose ps` | -| GET | `/stacks` | Lists all available Stacks | - -## Storage - -Stored in `stacks/` directory as: - -``` -/stacks - /my_stack - docker-compose.yaml - my-folder-for-a-service/... -``` \ No newline at end of file diff --git a/apps/docs/dockstat/archive/dockstatapi-v3/stacks/usage/README.md b/apps/docs/dockstat/archive/dockstatapi-v3/stacks/usage/README.md deleted file mode 100644 index 259f7559..00000000 --- a/apps/docs/dockstat/archive/dockstatapi-v3/stacks/usage/README.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -id: 8e733b65-5df2-4d8f-90e1-da8b127b2b27 -title: Usage -collectionId: b4a5e48f-f103-480b-9f50-8f53f515cab9 -parentDocumentId: 970cdf56-b108-4468-8d8a-4c9b7d71c2c3 -updatedAt: 2025-08-18T22:50:53.676Z -urlId: OaH8UQ4BB3 ---- - -## Endpoint - -``` -POST /stacks/deploy -``` - -### Description - -Deploys a new Docker stack using a provided Compose specification, allowing custom configurations and image updates. - - ---- - -## Request Structure - -| Field | Type | Required | Description | -|----|----|----|----| -| `name` | `string` | yes | Name of the stack to deploy. | -| `version` | `number` | yes | Version number of the stack configuration. | -| `custom` | `boolean` | yes | Whether to use a custom deployment process. | -| `source` | `string` | yes | Source identifier (e.g., repository or internal reference). | -| `compose_spec` | `object` | yes | JSON representation of a Docker Compose file. | - -The `compose_spec` object must conform to the `ComposeSpec` interface: - -```typescript -export interface ComposeSpec { - version?: string; - name?: string; - include?: Include[]; - services?: { [key: string]: Service }; - networks?: { [key: string]: Network }; - volumes?: { [key: string]: Volume }; - secrets?: { [key: string]: Secret }; - configs?: { [key: string]: Config }; - - // Allows custom extensions - [key: `x-${string}`]: any; -} -``` - - ---- - -## Responses - -* **200 OK** - * **Body**: `{ "message": "Stack