131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# π Artemis Backend Manager Container
|
|
|
|
The central orchestration, API gateway, authentication, and container lifecycle service for running Artemis and Cuttlefish on Google Cloud **Container-Optimized OS (COS)**.
|
|
|
|
---
|
|
|
|
## π Core Responsibilities
|
|
|
|
1. **Authentication & OTP Callbacks**:
|
|
- Manages user verification (`POST /api/v1/auth/otp/send` and `POST /api/v1/auth/otp/verify`).
|
|
- Issues signed JWT access tokens for secure tenant separation.
|
|
- Provides session validation hooks for Nginx ingress (`/api/v1/auth/validate-session`).
|
|
|
|
2. **Docker Socket Container Orchestration**:
|
|
- Communicates with `/var/run/docker.sock` to dynamically spawn `artemis-session-<session_id>` containers on the shared `artemis-net` bridge network.
|
|
- Injects runtime environment variables (`SESSION_ID`, `ADB_DEVICE_SERIAL`, `PORT=8080`).
|
|
- Automatically executes `adb connect` inside the container to pair it with the Cuttlefish emulator.
|
|
|
|
3. **Cloud Orchestrator & Cuttlefish Integration**:
|
|
- Dispatches API requests to the Cloud Orchestrator service running on COS to spin up dedicated Cuttlefish AVDs.
|
|
- Binds allocated ADB ports (`6520+N`) and WebRTC signaling ports (`8443+N`).
|
|
|
|
4. **BigQuery Mapping Store**:
|
|
- Tracks metadata linking `user_id`, `session_id`, `artemis_container_id`, `cuttlefish_adb_port`, `cuttlefish_webrtc_port`, and timestamps.
|
|
- Includes automatic partitioned table creation on BigQuery (`artemis_orchestration.sessions_registry`) and an in-memory fallback for local dev.
|
|
|
|
5. **Static Frontend UI Host**:
|
|
- Serves the dual-pane web application (Cuttlefish WebRTC stream player + Artemis agent thought workspace) at `/`.
|
|
|
|
6. **Automatic Session Reaper & Watchdog**:
|
|
- Background periodic worker checks active sessions every 30s.
|
|
- Automatically destroys orphaned containers and AVDs when the session TTL expires or heartbeat fails.
|
|
|
|
---
|
|
|
|
## π Directory Structure
|
|
|
|
```
|
|
playground/backend_manager/
|
|
βββ Dockerfile # Python 3.12 slim image with health check
|
|
βββ docker-compose.yml # Compose spec with /var/run/docker.sock mount
|
|
βββ requirements.txt # FastAPI, Pydantic, Docker SDK, BigQuery, JWT
|
|
βββ README.md # Detailed documentation
|
|
βββ app/
|
|
βββ main.py # FastAPI app entrypoint with lifespan manager
|
|
βββ config.py # Environment configuration settings
|
|
βββ auth/
|
|
β βββ jwt_handler.py # JWT encoding/decoding & get_current_user dependency
|
|
β βββ otp_service.py # OTP generation, storage, and verification
|
|
βββ services/
|
|
β βββ docker_service.py # Docker socket manager (start/stop containers)
|
|
β βββ cloud_orchestrator_service.py # Cloud Orchestrator Cuttlefish client
|
|
β βββ bigquery_service.py # BigQuery mapping repository with local fallback
|
|
β βββ session_manager.py # Master session lifecycle & reaper coordinator
|
|
βββ routers/
|
|
β βββ auth_router.py # OTP and JWT endpoints
|
|
β βββ session_router.py # Session creation, polling, heartbeat, and deletion
|
|
β βββ health_router.py # Liveness probe endpoint (/healthz)
|
|
βββ schemas/
|
|
β βββ auth_schema.py # Auth request/response schemas
|
|
β βββ session_schema.py # Session & mapping schemas
|
|
βββ static/
|
|
βββ index.html # Dual-pane glassmorphic web workspace
|
|
βββ style.css # Aurora design system styling
|
|
βββ app.js # Frontend client logic & streaming hooks
|
|
```
|
|
|
|
---
|
|
|
|
## π REST API Endpoints
|
|
|
|
### Authentication
|
|
* `POST /api/v1/auth/otp/send` β Request a 6-digit OTP code (`{"identifier": "user@example.com"}`).
|
|
* `POST /api/v1/auth/otp/verify` β Verify OTP code and receive signed JWT token (`{"identifier": "...", "code": "123456"}`).
|
|
* `GET /api/v1/auth/me` β Return profile of the current authenticated user (`Authorization: Bearer <jwt>`).
|
|
* `GET /api/v1/auth/validate-session?session_id=...` β Validate user authorization for a specific session.
|
|
|
|
### Sessions & Container Management
|
|
* `POST /api/v1/sessions/create` β Provision Cuttlefish AVD + Artemis container, link ADB, and register mapping.
|
|
* `GET /api/v1/sessions` β List all active sessions for the current user.
|
|
* `GET /api/v1/sessions/{session_id}` β Get session status and reverse-proxy stream endpoints.
|
|
* `POST /api/v1/sessions/{session_id}/heartbeat` β Send client heartbeat to extend session TTL.
|
|
* `DELETE /api/v1/sessions/{session_id}` β Terminate container and release Cuttlefish instance.
|
|
|
|
### Health Probe
|
|
* `GET /healthz` β Returns `200 OK` with service health status.
|
|
|
|
---
|
|
|
|
## βοΈ Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
| :--- | :--- | :--- |
|
|
| `PORT` | `8000` | HTTP port to listen on |
|
|
| `APP_ENV` | `development` | Environment mode (`development` / `production`) |
|
|
| `JWT_SECRET_KEY` | `artemis-...` | Secret key for signing JWT session tokens |
|
|
| `DOCKER_SOCKET_PATH` | `unix://var/run/docker.sock` | Path to host Docker daemon socket |
|
|
| `DOCKER_NETWORK` | `artemis-net` | Shared bridge network for dynamic container routing |
|
|
| `ARTEMIS_IMAGE` | `artemis:latest` | Docker image to spawn for Artemis instances |
|
|
| `CLOUD_ORCHESTRATOR_URL` | `http://host.docker.internal:1443` | Endpoint of the Cloud Orchestrator service |
|
|
| `CUTTLEFISH_HOST_GATEWAY` | `host.docker.internal` | Host IP / gateway for ADB TCP connections |
|
|
| `GOOGLE_CLOUD_PROJECT` | `artemis-cloud-project` | GCP project ID for BigQuery dataset |
|
|
| `USE_LOCAL_FALLBACK_DB` | `true` | Enables in-memory DB fallback if BigQuery is unconfigured |
|
|
| `SESSION_TTL_MINUTES` | `60` | Default session lifespan before automatic teardown |
|
|
|
|
---
|
|
|
|
## π Running the Container
|
|
|
|
### 1. Build Image
|
|
```bash
|
|
docker build -t artemis-backend-manager:latest .
|
|
```
|
|
|
|
### 2. Run with Docker Compose
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 3. Run Standalone with Docker on COS
|
|
```bash
|
|
docker run -d \
|
|
--name backend \
|
|
--restart unless-stopped \
|
|
--network artemis-net \
|
|
--add-host host.docker.internal:host-gateway \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-p 8000:8000 \
|
|
artemis-backend-manager:latest
|
|
```
|