feat: embed frontend into backend server with full-stack build pipeline (RCA-20)

The backend now serves the Vue admin UI as static files with SPA fallback, eliminating the need for a separate web server. Dockerfile builds both frontend and backend in a multi-stage pipeline. Added build:web and build:all scripts, updated CI to verify frontend builds, and fixed vitest config to exclude Playwright tests. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-18 12:33:41 +08:00
parent 1093d64724
commit fb5c841282
10 changed files with 241 additions and 15 deletions
--- a/README.md
+++ b/README.md
@@ -10,8 +10,10 @@ CookieBridge syncs browser cookies across devices through an encrypted relay ser
 - **Multi-browser support** — Chrome, Firefox, Edge, and Safari extensions.
 - **Real-time sync** — WebSocket transport with HTTP polling fallback.
 - **Device pairing** — 6-digit code, 5-minute TTL, X25519 key exchange.
+- **Admin panel** — Built-in Vue 3 web UI for server management.
 - **AI agent API** — Agents can retrieve encrypted cookies with granted access.
 - **Conflict resolution** — Last-writer-wins with Lamport clocks.
+- **Database options** — In-memory (default), SQLite, or MySQL via setup wizard.
 - **Self-hostable** — Docker image or run directly with Node.js.

 ## Quick Start
@@ -22,7 +24,9 @@ CookieBridge syncs browser cookies across devices through an encrypted relay ser
 docker compose up -d
 ```

-The relay server starts on port 8080. Override with `PORT=3000 docker compose up -d`.
+The server starts on port 8080 with the admin UI embedded. Override the port with `PORT=3000 docker compose up -d`.
+
+Open `http://localhost:8080` to access the admin panel and run the setup wizard.

 ### Docker (manual)

@@ -34,11 +38,30 @@ docker run -d -p 8080:8080 --name cookiebridge cookiebridge
 ### From source

 ```bash
+# Install all dependencies
 npm install
+cd web && npm install && cd ..
+
+# Build everything (backend + frontend)
+npm run build:all
+
+# Start the server (serves API + admin UI)
 npm start
 ```

-Requires Node.js 22+. The server listens on `0.0.0.0:8080` by default.
+Requires Node.js 22+. The server listens on `0.0.0.0:8080` by default and serves the admin UI at the root URL.
+
+### Development mode
+
+Run the backend and frontend dev servers separately for hot-reload:
+
+```bash
+# Terminal 1: Backend (port 8080)
+npm run dev
+
+# Terminal 2: Frontend dev server (port 5173, proxies API to backend)
+cd web && npm run dev
+```

 ## Environment Variables

@@ -77,15 +100,15 @@ Output goes to `extension/build/{browser}/`. Load the unpacked extension from th

 ```
 Browser Extension ──WebSocket/HTTP──▶ Relay Server (stores encrypted blobs)
-     │                                      ▲
-     ├── Ed25519 signing                    │
-     ├── X25519 key exchange                │
-     └── XChaCha20-Poly1305 encryption      │
-                                            │
-AI Agent ──Bearer token──────────────────────┘
+     │                                   │
+     ├── Ed25519 signing                 ├── Admin UI (Vue 3 SPA)
+     ├── X25519 key exchange             ├── SQLite / MySQL / In-memory
+     └── XChaCha20-Poly1305 encryption   └── Setup wizard
+                                         │
+AI Agent ──Bearer token──────────────────┘
 ```

-The relay server is a plain Node.js HTTP + WebSocket server with no framework dependencies. See [docs/architecture.md](docs/architecture.md) for the full design and [docs/security.md](docs/security.md) for the threat model.
+The relay server is a plain Node.js HTTP + WebSocket server with no framework dependencies. In production, the server embeds the pre-built admin UI and serves it as static files. See [docs/architecture.md](docs/architecture.md) for the full design and [docs/security.md](docs/security.md) for the threat model.

 ## API Endpoints

@@ -104,6 +127,46 @@ The relay server is a plain Node.js HTTP + WebSocket server with no framework de
 | `GET` | `/health` | Health check |
 | `WebSocket` | `/ws` | Real-time sync channel |

+### Admin Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/admin/setup/init` | Run setup wizard (set password, choose DB) |
+| `GET` | `/admin/setup/status` | Check if setup has been completed |
+| `POST` | `/admin/login` | Login to admin panel |
+| `GET` | `/admin/devices` | List registered devices |
+| `GET` | `/admin/connections` | List active WebSocket connections |
+| `GET` | `/admin/agents` | List registered agents |
+| `GET` | `/admin/stats` | Server statistics |
+
+## Deployment
+
+### Build Pipeline
+
+The Dockerfile uses a multi-stage build:
+
+1. **web-builder** — Installs frontend dependencies and runs `vite build`
+2. **builder** — Compiles the TypeScript backend
+3. **production** — Copies compiled backend + built frontend into a minimal image
+
+The frontend is served from the `/public` directory inside the container. No separate web server (nginx, etc.) is needed.
+
+### Database Persistence
+
+By default, CookieBridge starts with in-memory storage. On first access, the setup wizard lets you choose:
+
+- **In-memory** — No persistence, data resets on restart
+- **SQLite** — File-based, mount a volume for persistence
+- **MySQL** — Remote database, provide connection details
+
+For SQLite persistence with Docker:
+
+```bash
+docker run -d -p 8080:8080 -v cookiebridge-data:/app/data cookiebridge
+```
+
+Database configuration is stored in `data/db-config.json`.
+
 ## Development

 ```bash
@@ -111,6 +174,7 @@ npm install
 npm run dev          # Start with file watching
 npm test             # Run test suite
 npm run typecheck    # Type checking only
+npm run build:all    # Build backend + frontend
 ```

 ## Project Structure
@@ -119,18 +183,21 @@ npm run typecheck    # Type checking only
 src/
  cli.ts             # Server entry point
  relay/
-    server.ts        # HTTP + WebSocket server
+    server.ts        # HTTP + WebSocket server + static file serving
+    static.ts        # Static file serving with SPA fallback
    connections.ts   # WebSocket connection manager
    auth.ts          # Token & challenge-response auth
-    store.ts         # In-memory encrypted cookie storage
-    tokens.ts        # Device & agent registries
+    admin/           # Admin panel API routes
+    db/              # Database abstraction (memory, SQLite, MySQL)
  crypto/            # XChaCha20-Poly1305, Ed25519
  pairing/           # Device pairing flow
  sync/              # Sync engine, conflict resolution
  protocol/
    spec.ts          # Protocol types & constants
+web/                 # Admin panel (Vue 3 + Vite)
 extension/           # Multi-browser extension source
 tests/               # Vitest test suite
+docs/                # Architecture and security docs
 ```

 ## License