### Setup Frontend

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Installs dependencies and starts the frontend development server.

```bash
cd ExcaliDash/frontend
npm install

# Copy environment file and customize if needed
cp .env.example .env

npm run dev
```

--------------------------------

### Setup Backend

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Installs dependencies, generates the Prisma client, and starts the backend development server.

```bash
cd ExcaliDash/backend
npm install

# Copy environment file and customize if needed
cp .env.example .env

# Generate Prisma client and setup database
npx prisma generate
npx prisma db push

npm run dev
```

--------------------------------

### Quickstart Deployment via Docker Hub

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Commands to download the production compose file and start the service.

```bash
# Download docker-compose.prod.yml
curl -OL https://raw.githubusercontent.com/ZimengXiong/ExcaliDash/main/docker-compose.prod.yml

# Pull images
docker compose -f docker-compose.prod.yml pull

# Run container
docker compose -f docker-compose.prod.yml up -d

# Access the frontend at localhost:6767
```

--------------------------------

### Install and Development Commands

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Commands for installing dependencies and starting development servers for the backend and frontend.

```bash
make install
```

```bash
make dev
```

```bash
make dev-backend
```

```bash
make dev-frontend
```

--------------------------------

### Backend Express and Socket.IO Setup

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Shows the setup of the Express app, Socket.IO server, middleware, routes, and startup guards in the backend.

```typescript
backend/src/index.ts
```

--------------------------------

### Retrieve Bootstrap Setup Code

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Find the one-time admin setup code in the backend logs. This code is required for initial user setup when authentication is enabled.

```bash
docker compose -f docker-compose.prod.yml logs backend --tail=200 | grep "BOOTSTRAP SETUP"
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/zimengxiong/excalidash/blob/main/e2e/README.md

Install project dependencies and Playwright browsers, then run the test suite. Use `npm run test:headed` to see the browser or `npm run test:debug` for debugging.

```bash
npm install
npx playwright install chromium

npm test

npm run test:headed

npm run test:debug
```

--------------------------------

### Deploy ExcaliDash with Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Commands to download the production configuration and start the services.

```bash
curl -OL https://raw.githubusercontent.com/ZimengXiong/ExcaliDash/main/docker-compose.prod.yml
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```

--------------------------------

### Backend Admin and Development Scripts

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Examples of backend scripts available in package.json for administrative tasks and development simulations.

```bash
npm run admin:recover
```

```bash
npm run dev:simulate-auth-onboarding:*
```

--------------------------------

### Start Local OIDC Test Stack

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Initializes the Keycloak container for OIDC testing. Ensure the admin password is set before execution.

```bash
# From repo root
# Choose a strong password; do not commit it.
export KEYCLOAK_ADMIN_PASSWORD='...'
docker compose -f docker-compose.oidc.yml up -d
```

--------------------------------

### Configure Docker Image Tags

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Examples for pinning specific versions or switching to development image tags in docker-compose.yml.

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:0.4.18
  frontend:
    image: zimengxiong/excalidash-frontend:0.4.18
```

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:dev
  frontend:
    image: zimengxiong/excalidash-frontend:dev
```

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:0.4.18-dev
  frontend:
    image: zimengxiong/excalidash-frontend:0.4.18-dev
```

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:0.4.18-dev-issue38
  frontend:
    image: zimengxiong/excalidash-frontend:0.4.18-dev-issue38
```

--------------------------------

### GET /export/excalidash

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Exports the user's data as a portable .excalidash file.

```APIDOC
## GET /export/excalidash

### Description
Exports the user's data as a portable .excalidash file (or .zip).

### Method
GET

### Endpoint
/export/excalidash

### Parameters
#### Query Parameters
- **ext** (string) - Optional - File extension, e.g., 'zip'.

### Response
#### Success Response (200)
- **file** (binary) - The exported .excalidash or .zip file.
```

--------------------------------

### GET /system/update

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Checks for available software updates.

```APIDOC
## GET /system/update

### Description
Checks for available updates based on the specified release channel.

### Method
GET

### Endpoint
/system/update

### Parameters
#### Query Parameters
- **channel** (string) - Required - The release channel (e.g., 'stable').

### Response
#### Success Response (200)
- **currentVersion** (string) - Current version installed.
- **latestVersion** (string) - Latest available version.
- **isUpdateAvailable** (boolean) - Whether an update is available.
```

--------------------------------

### GET /health

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Performs a system health check.

```APIDOC
## GET /health

### Description
Checks if the system is operational.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The status of the system (e.g., 'ok').
```

--------------------------------

### GET /library

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves the user's library items.

```APIDOC
## GET /library

### Description
Fetches library items for the authenticated user.

### Method
GET

### Endpoint
http://localhost:8000/library

### Response
#### Success Response (200)
- **items** (array) - List of library items
```

--------------------------------

### Run Tests with Existing Servers

Source: https://github.com/zimengxiong/excalidash/blob/main/e2e/README.md

Execute tests without starting new servers, assuming backend is at http://localhost:8000 and frontend at http://localhost:5173. Set the `NO_SERVER` environment variable to true.

```bash
# Backend at http://localhost:8000
# Frontend at http://localhost:5173
NO_SERVER=true npm test
```

--------------------------------

### Create GitHub Issue with GitHub CLI

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Initiate the process of creating a new GitHub issue using a guided workflow with the GitHub CLI.

```bash
gh issue create
```

--------------------------------

### Get User Library Items

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieve all items from the current user's Excalidraw library. Requires a valid JWT token.

```bash
curl -X GET "http://localhost:8000/library" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### Get Auth Status

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves the current authentication status and mode of the Excalidash instance. No authentication required.

```bash
curl -X GET "http://localhost:8000/auth/status"
```

--------------------------------

### View Backend Logs with Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Retrieve the last 200 lines of logs from the backend service when using the default Docker Compose setup.

```bash
docker compose logs backend --tail=200
```

--------------------------------

### Get Current User Information

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieve details of the currently authenticated user. Requires an access token in the Cookie header.

```bash
curl -X GET "http://localhost:8000/auth/me" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### Basic Playwright Test Example

Source: https://github.com/zimengxiong/excalidash/blob/main/e2e/README.md

A simple Playwright test case demonstrating navigation to the root path, asserting the visibility of an `h1` element, and making an API request to check the backend status.

```typescript
import { test, expect } from "@playwright/test";

test("my test", async ({ page, request }) => {
  await page.goto("/");
  await expect(page.locator("h1")).toBeVisible();
  
  const response = await request.get("http://localhost:8000/drawings");
  expect(response.ok()).toBe(true);
});
```

--------------------------------

### Get Sharing Settings

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves the sharing settings for a specific drawing, including user permissions and link-based sharing configurations. Requires JWT token.

```bash
curl -X GET "http://localhost:8000/drawings/uuid-1234/sharing" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### Build from Source

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Commands to clone the repository and build the containers locally.

```bash
# Clone the repository (recommended)
git clone git@github.com:ZimengXiong/ExcaliDash.git

# or, clone with HTTPS
# git clone https://github.com/ZimengXiong/ExcaliDash.git

docker compose build
docker compose up -d

# Access the frontend at localhost:6767
```

--------------------------------

### Configure Backend for OIDC

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Prepares the backend environment for hybrid OIDC authentication.

```bash
cd backend
cp .env.oidc.example .env
# Ensure OIDC_REDIRECT_URI matches where your frontend is running:
# - http://localhost:6767/api/auth/oidc/callback (repo frontend dev default)
# - https://excalidash.example.com/api/auth/oidc/callback (production)
```

--------------------------------

### Simulate Auth Onboarding

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Executes scripts to simulate different authentication onboarding states for local development.

```bash
cd ExcaliDash/backend

# Preview what would change (no data modifications)
npm run dev:simulate-auth-onboarding:dry-run

# Simulate "fresh install" onboarding state
# (wipes drawings/collections/libraries and removes non-bootstrap users)
npm run dev:simulate-auth-onboarding:fresh

# Simulate "migration" onboarding state (ensures legacy data exists)
npm run dev:simulate-auth-onboarding:migration
```

--------------------------------

### GET /auth/admin/users

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Lists all users in the system (Admin only).

```APIDOC
## GET /auth/admin/users

### Description
Retrieves a list of all users.

### Method
GET

### Endpoint
http://localhost:8000/auth/admin/users

### Response
#### Success Response (200)
- **users** (array) - List of user objects
```

--------------------------------

### GET /auth/me

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves the currently authenticated user's profile.

```APIDOC
## GET /auth/me

### Description
Fetches the current user's profile information.

### Method
GET

### Endpoint
http://localhost:8000/auth/me

### Response
#### Success Response (200)
- **user** (object) - Current user profile
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Standard commands for setting up and running the development environment.

```bash
make install
make dev
make dev-stop
make dev-backend
make dev-frontend
```

--------------------------------

### Build, Test, and Lint Commands

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Makefile commands for building the project, running linters, and executing various test suites.

```bash
make build
```

```bash
make lint
```

```bash
make test
```

```bash
make test-all
```

```bash
make test-e2e
```

```bash
make test-e2e-docker
```

--------------------------------

### Reproduce Issue Locally

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Steps to reproduce an issue in a minimal local development environment.

```bash
make dev
open http://localhost:6767
```

--------------------------------

### Initialize Real-Time Collaboration

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Connect to the Socket.IO server and join a specific drawing room to receive updates.

```javascript
import { io } from "socket.io-client";

const socket = io("http://localhost:8000", {
  withCredentials: true,
  auth: { token: accessToken } // Optional, can use cookie-based auth
});

// Join a drawing room
socket.emit("join-room", {
  drawingId: "uuid-1234",
  user: {
    id: "user-id",
    name: "John Doe",
    color: "#4f46e5"
  }
}, (response) => {
  // Server returns canonical user identity
  console.log("Joined as:", response.user);
});

// Listen for presence updates
socket.on("presence-update", (users) => {
  // users: [{id, name, initials, color, socketId, isActive}, ...]
  console.log("Users in room:", users);
});

// Listen for element updates from other users
socket.on("element-update", (data) => {
  // data: {drawingId, elements, appState, ...}
  applyRemoteChanges(data);
});

// Listen for cursor movements
socket.on("cursor-move", (data) => {
  // data: {drawingId, userId, username, color, x, y}
  updateRemoteCursor(data);
});
```

--------------------------------

### Bootstrap Registration (First Admin)

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Use this endpoint to register the initial administrator account. Requires a CSRF token.

```bash
curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{
    "email": "admin@example.com",
    "password": "SecureP@ss123",
    "name": "Admin User",
    "setupCode": "ABC123"
  }'
```

--------------------------------

### Create New User (Admin)

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Create a new user account. Supports both local authentication with a password and OIDC-only users. Requires admin privileges and a CSRF token.

```bash
curl -X POST "http://localhost:8000/auth/admin/users" \
  -H "Cookie: access_token=<admin_jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{
    "email": "newuser@example.com",
    "password": "TempP@ss123",
    "name": "New User",
    "role": "USER",
    "mustResetPassword": true,
    "isActive": true
  }'
```

```bash
curl -X POST "http://localhost:8000/auth/admin/users" \
  -H "Cookie: access_token=<admin_jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{
    "email": "oidcuser@example.com",
    "name": "OIDC User",
    "oidcOnly": true
  }'
```

--------------------------------

### Frontend Production Serving and Proxy

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Details the Dockerfile, Nginx configuration template, and entrypoint script for production serving and backend proxying in the frontend.

```bash
frontend/Dockerfile
```

```nginx
frontend/nginx.conf.template
```

```bash
frontend/docker-entrypoint.sh
```

--------------------------------

### Backend Dockerfile Build Process

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Outlines the build pipeline for the backend runtime, including Prisma generation and TypeScript compilation.

```dockerfile
backend/Dockerfile
```

--------------------------------

### Backend Authentication and Routes

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

References the files containing authentication, session management, and onboarding logic in the backend.

```typescript
backend/src/auth.ts
```

```typescript
backend/src/auth/*
```

```typescript
backend/src/routes/*
```

--------------------------------

### Drawings API - Get Single Drawing

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves a complete drawing by ID including elements, appState, and files. Supports shared access via link sharing.

```APIDOC
## GET /drawings/{id}

### Description
Retrieves a complete drawing by ID including elements, appState, and files. Supports shared access via link sharing.

### Method
GET

### Endpoint
/drawings/{id}

#### Path Parameters
- **id** (string) - Required - The unique identifier of the drawing to retrieve.

### Request Example
```bash
curl -X GET "http://localhost:8000/drawings/uuid-1234"
  -H "Cookie: access_token=<jwt_token>"
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the drawing.
- **name** (string) - Name of the drawing.
- **collectionId** (string) - ID of the collection the drawing belongs to.
- **elements** (array) - Array of drawing elements.
- **appState** (object) - Application state for the drawing.
- **files** (object) - Associated files for the drawing.
- **preview** (string) - SVG preview of the drawing.
- **version** (integer) - Current version of the drawing.
- **accessLevel** (string) - User's access level to the drawing (e.g., 'owner').
- **createdAt** (string) - Timestamp when the drawing was created.
- **updatedAt** (string) - Timestamp when the drawing was last updated.

#### Response Example
```json
{
  "id": "uuid-1234",
  "name": "System Architecture",
  "collectionId": "collection-id",
  "elements": [{"type": "rectangle", "x": 100, "y": 100, ...}],
  "appState": {"viewBackgroundColor": "#ffffff", "gridSize": null, ...},
  "files": {"file-id-1": {"mimeType": "image/png", "dataURL": "data:..."}},
  "preview": "<svg>...</svg>",
  "version": 5,
  "accessLevel": "owner",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:22:00.000Z"
}
```
```

--------------------------------

### Backend Configuration Loading

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Illustrates how environment variables are loaded and validated in the backend configuration.

```typescript
backend/src/config.ts
```

--------------------------------

### List Services with Production Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

List the running services defined in the production Docker Compose file.

```bash
docker compose -f docker-compose.prod.yml ps
```

--------------------------------

### Get Single Drawing

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves a specific drawing by its ID, including all its elements, app state, and associated files. Supports shared access via link sharing.

```bash
curl -X GET "http://localhost:8000/drawings/uuid-1234" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### List Services with Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

List the running services defined in the default Docker Compose file.

```bash
docker compose ps
```

--------------------------------

### Import Backup via REST API

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Restore data from an .excalidash file. Requires both a JWT access token and a CSRF token.

```bash
curl -X POST "http://localhost:8000/import/excalidash" \
  -H "Cookie: access_token=<jwt_token>" \
  -H "x-csrf-token: <csrf_token>" \
  -F "file=@backup.excalidash"
```

--------------------------------

### POST /import/excalidash

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Imports a previously exported .excalidash backup file.

```APIDOC
## POST /import/excalidash

### Description
Imports a backup file to restore collections and drawings.

### Method
POST

### Endpoint
/import/excalidash

### Request Body
- **file** (file) - Required - The .excalidash backup file.

### Response
#### Success Response (200)
- **imported** (object) - Counts of imported collections and drawings.
- **skipped** (object) - Counts of skipped collections and drawings.

#### Response Example
{
  "imported": {"collections": 5, "drawings": 42},
  "skipped": {"collections": 0, "drawings": 2}
}
```

--------------------------------

### POST /auth/register

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Registers the first administrator for the system.

```APIDOC
## POST /auth/register

### Description
Registers the first admin user for the application.

### Method
POST

### Endpoint
http://localhost:8000/auth/register

### Request Body
- **email** (string) - Required - Admin email address
- **password** (string) - Required - Secure password
- **name** (string) - Required - Admin name
- **setupCode** (string) - Required - Setup verification code

### Response
#### Success Response (200)
- **user** (object) - Created user details
```

--------------------------------

### Backend Runtime Migration Handling

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Specifies the script responsible for handling runtime migrations within the backend Docker entrypoint.

```bash
backend/docker-entrypoint.sh
```

--------------------------------

### Docker Management Commands

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Makefile commands for building, running, and managing Docker containers for the project.

```bash
make docker-build
```

```bash
make docker-run
```

```bash
make docker-run-detached
```

```bash
make docker-ps
```

```bash
make docker-logs
```

```bash
make docker-down
```

--------------------------------

### Export Backup via REST API

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Download application data as a portable .excalidash archive. Requires a valid JWT access token in the cookie.

```bash
curl -X GET "http://localhost:8000/export/excalidash" \
  -H "Cookie: access_token=<jwt_token>" \
  -o backup.excalidash

curl -X GET "http://localhost:8000/export/excalidash?ext=zip" \
  -H "Cookie: access_token=<jwt_token>" \
  -o backup.excalidash.zip
```

--------------------------------

### Set Default Repository with GitHub CLI

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Configure the GitHub CLI to target the ExcaliDash repository for subsequent commands.

```bash
gh repo set-default ZimengXiong/ExcaliDash
```

--------------------------------

### Restart ExcaliDash Services with Pinned Images

Source: https://github.com/zimengxiong/excalidash/blob/main/scripts/release-notes-template.md

After pinning images in your docker-compose.prod.yml, use this command to apply the changes and restart the services.

```bash
docker compose -f docker-compose.prod.yml up -d
```

--------------------------------

### Initialize Excalidraw Asset Path

Source: https://github.com/zimengxiong/excalidash/blob/main/frontend/index.html

Sets the global EXCALIDRAW_ASSET_PATH variable if it is not already defined, ensuring assets are loaded from the correct base URL.

```javascript
(function () { if (typeof window.EXCALIDRAW_ASSET_PATH === "string" && window.EXCALIDRAW_ASSET_PATH.length > 0) return; var base = "%BASE_URL%"; if (base === "%BASE_URL%") base = "/"; if (base && base[base.length - 1] !== "/") base += "/"; window.EXCALIDRAW_ASSET_PATH = new URL(base || "/", window.location.origin).toString(); })();
```

--------------------------------

### List All Users (Admin)

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieve a list of all users in the system. This endpoint is for administrators and requires an admin access token.

```bash
curl -X GET "http://localhost:8000/auth/admin/users" \
  -H "Cookie: access_token=<admin_jwt_token>"
```

--------------------------------

### Access ExcaliDash

Source: https://context7.com/zimengxiong/excalidash/llms.txt

The default URL to access the ExcaliDash application after deployment.

```bash
# Access at http://localhost:6767
```

--------------------------------

### Register User

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Registers a new user with email, password, and name. Requires CSRF token and a JSON payload with user details. Authentication is not required for registration.

```bash
curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{
    "email": "user@example.com",
    "password": "SecureP@ss123",
    "name": "John Doe"
  }'
```

--------------------------------

### Toggle User Registration (Admin)

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Enable or disable new user registrations globally. Requires admin privileges and a CSRF token.

```bash
curl -X POST "http://localhost:8000/auth/admin/registration/toggle" \
  -H "Cookie: access_token=<admin_jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{"enabled": false}'
```

--------------------------------

### Clone Repository

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Downloads the source code from the remote repository.

```bash
# Clone the repository (recommended)
git clone git@github.com:ZimengXiong/ExcaliDash.git

# or, clone with HTTPS
# git clone https://github.com/ZimengXiong/ExcaliDash.git
```

--------------------------------

### ExcaliDash Production Docker Compose Configuration

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Defines the services, environment variables, and volumes for a production deployment of ExcaliDash backend and frontend.

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:latest
    environment:
      - DATABASE_URL=file:/app/prisma/dev.db
      - PORT=8000
      - NODE_ENV=production
      - AUTH_MODE=local  # or hybrid, oidc_enforced
      - TRUST_PROXY=false  # Set to 1 behind reverse proxy
      - JWT_SECRET=${JWT_SECRET}
      - CSRF_SECRET=${CSRF_SECRET}
      # OIDC configuration (for hybrid/oidc_enforced modes)
      # - OIDC_PROVIDER_NAME=Authentik
      # - OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
      # - OIDC_CLIENT_ID=your-client-id
      # - OIDC_CLIENT_SECRET=your-client-secret
      # - OIDC_REDIRECT_URI=https://excalidash.example.com/api/auth/oidc/callback
    volumes:
      - backend-data:/app/prisma
    restart: unless-stopped

  frontend:
    image: zimengxiong/excalidash-frontend:latest
    ports:
      - "6767:80"
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  backend-data:
```

--------------------------------

### OIDC Configuration for Excalidash Backend

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Configure OIDC authentication for Excalidash by setting backend environment variables. This includes provider details, client ID, and redirect URI.

```yaml
backend:
  environment:
    - AUTH_MODE=oidc_enforced
    - OIDC_PROVIDER_NAME=Authentik
    - OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
    - OIDC_CLIENT_ID=your-client-id
    # Optional for public clients; required for confidential clients
    # - OIDC_CLIENT_SECRET=your-client-secret
    # Optional override when your IdP client is configured for a non-default ID token alg
    # - OIDC_ID_TOKEN_SIGNED_RESPONSE_ALG=HS256
    - OIDC_REDIRECT_URI=https://excalidash.example.com/api/auth/oidc/callback
    - OIDC_SCOPES=openid profile email
```

--------------------------------

### Create Drawing

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Creates a new drawing with optional initial data such as name, collection assignment, and content. Requires CSRF token for authentication.

```bash
curl -X POST "http://localhost:8000/drawings" \
  -H "Cookie: access_token=<jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{
    "name": "New Architecture Diagram",
    "collectionId": "collection-uuid",
    "elements": [],
    "appState": {"viewBackgroundColor": "#ffffff"},
    "files": {}
  }'
```

--------------------------------

### OIDC Sign-In Initiation

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Initiate the OpenID Connect (OIDC) sign-in flow by redirecting the frontend to the OIDC provider. The backend handles the callback at /api/auth/oidc/callback.

```javascript
window.location.href = "/api/auth/oidc/start?returnTo=/dashboard";
```

--------------------------------

### Monitor and Maintain Production Services

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Common commands for checking service health, viewing logs, and performing upgrades.

```bash
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs backend --tail=200
docker compose -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml logs backend --tail=200 | grep "BOOTSTRAP SETUP"
docker compose up -d
```

--------------------------------

### Backend Prisma Client Wrapper

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Details the wrapper for Prisma client, including caching behavior in non-production environments.

```typescript
backend/src/db/prisma.ts
```

--------------------------------

### Search GitHub Issues with GitHub CLI

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Search for issues within the ExcaliDash repository using keywords. Replace "<error snippet>" with the actual error text or symptom.

```bash
gh issue list --search "<error snippet>"
```

--------------------------------

### Create Link Share

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Creates a shareable link for a drawing. Can specify permission ('view' or 'edit') and an optional expiration date.

```bash
# Create view-only link (non-expiring by default)
curl -X POST "http://localhost:8000/drawings/uuid-1234/link-shares" \
  -H "Cookie: access_token=<jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{"permission": "view"}'
```

```bash
# Create edit link with custom expiration
curl -X POST "http://localhost:8000/drawings/uuid-1234/link-shares" \
  -H "Cookie: access_token=<jwt_token>" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{"permission": "edit", "expiresAt": "2024-02-01T00:00:00.000Z"}'
```

--------------------------------

### Frontend State Management Context

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Points to the directory containing frontend state management for authentication and theme.

```typescript
frontend/src/context/
```

--------------------------------

### List All Drawings

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Retrieves a paginated list of drawings for the authenticated user. Use `includeData=true` to fetch full drawing content.

```bash
# Get all drawings (summary view)
curl -X GET "http://localhost:8000/drawings" \
  -H "Cookie: access_token=<jwt_token>" \
  -H "Content-Type: application/json"
```

```bash
# Get drawings with full data
curl -X GET "http://localhost:8000/drawings?includeData=true" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### POST /auth/login

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Authenticates a user and sets authentication cookies.

```APIDOC
## POST /auth/login

### Description
Logs in a user and returns authentication cookies.

### Method
POST

### Endpoint
http://localhost:8000/auth/login

### Request Body
- **email** (string) - Required - User email
- **password** (string) - Required - User password

### Response
#### Success Response (200)
- **user** (object) - Authenticated user details
```

--------------------------------

### Frontend API Client and Endpoints

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

References the file containing the API client and authentication/update endpoints for the frontend.

```typescript
frontend/src/api/index.ts
```

--------------------------------

### Upgrade Docker Containers

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Commands to pull the latest images and recreate containers for production deployments.

```bash
docker compose -f docker-compose.prod.yml pull && \
  docker compose -f docker-compose.prod.yml up -d
```

```bash
docker compose -f docker-compose.prod.yml down && \
  docker compose -f docker-compose.prod.yml pull && \
  docker compose -f docker-compose.prod.yml up -d
```

--------------------------------

### Frontend API Client Usage

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Interact with the ExcaliDash backend using the provided TypeScript client, which handles authentication and CSRF automatically.

```typescript
import {
  api,
  getDrawings,
  createDrawing,
  updateDrawing,
  getCollections,
  authLogin,
  authLogout,
  getSharedDrawings
} from "./api";

// Fetch drawings with pagination and filtering
const { drawings, totalCount } = await getDrawings(
  "search term",  // optional search
  "collection-id", // optional collection filter (null for unorganized, "trash" for trash)
  {
    limit: 20,
    offset: 0,
    sortField: "updatedAt",
    sortDirection: "desc"
  }
);

// Fetch drawings shared with current user
const { drawings: sharedDrawings } = await getSharedDrawings();

// Create and update drawings
const newDrawing = await createDrawing("My Diagram", "collection-id");
const updated = await updateDrawing(newDrawing.id, {
  name: "Renamed Diagram",
  elements: [...],
  appState: {...},
  version: 1
});

// Authentication
await authLogin("user@example.com", "password");
await authLogout();
```

--------------------------------

### User Login

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Authenticate a user by email and password. This endpoint sets httpOnly cookies for access and refresh tokens upon successful login.

```bash
curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: <csrf_token>" \
  -d '{"email": "user@example.com", "password": "SecureP@ss123"}'
```

--------------------------------

### Docker Compose Frontend Environment Variables

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Configure frontend environment variables for backend service discovery. Use the service DNS name for Kubernetes deployments.

```yaml
frontend:
  environment:
    # For standard Docker Compose (default)
    # - BACKEND_URL=backend:8000
    # For Kubernetes, use the service DNS name:
    - BACKEND_URL=excalidash-backend.default.svc.cluster.local:8000
```

--------------------------------

### Pull and Update ExcaliDash Docker Images

Source: https://github.com/zimengxiong/excalidash/blob/main/scripts/release-notes-template.md

Use these commands to pull the latest ExcaliDash images and restart the services in detached mode.

```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```

--------------------------------

### View Backend Logs with Production Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Retrieve the last 200 lines of logs from the backend service when using the production Docker Compose configuration.

```bash
docker compose -f docker-compose.prod.yml logs backend --tail=200
```

--------------------------------

### System Health and Update Checks

Source: https://context7.com/zimengxiong/excalidash/llms.txt

Endpoints for verifying system status and checking for available software updates.

```bash
curl -X GET "http://localhost:8000/health"

curl -X GET "http://localhost:8000/system/update?channel=stable" \
  -H "Cookie: access_token=<jwt_token>"
```

--------------------------------

### Docker Compose Backend Environment Variables

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Configure backend environment variables for frontend URLs and trust proxy settings. Supports single or multiple comma-separated URLs for FRONTEND_URL.

```yaml
backend:
  environment:
    # Single URL
    - FRONTEND_URL=https://excalidash.example.com
    # Trust exactly one reverse-proxy hop
    - TRUST_PROXY=1
    # Or multiple URLs (comma-separated) for local + network access
    # - FRONTEND_URL=http://localhost:6767,http://192.168.1.100:6767,http://nas.local:6767
```

--------------------------------

### Frontend Vite Configuration

Source: https://github.com/zimengxiong/excalidash/blob/main/AGENTS.md

Specifies the Vite configuration file used for setting up the backend proxy in local development and defining app metadata.

```typescript
frontend/vite.config.ts
```

--------------------------------

### Pin ExcaliDash Docker Images to Specific Release

Source: https://github.com/zimengxiong/excalidash/blob/main/scripts/release-notes-template.md

Modify your docker-compose.prod.yml file to pin the backend and frontend images to a specific release tag for reproducible deployments.

```yaml
services:
  backend:
    image: zimengxiong/excalidash-backend:{{TAG}}
  frontend:
    image: zimengxiong/excalidash-frontend:{{TAG}}
```

--------------------------------

### Admin Recovery Script

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Use this script for emergency admin credential recovery or reset. It requires navigating to the backend directory and running the npm script with specific flags.

```bash
cd backend
npm run admin:recover -- --identifier admin@example.com --generate --activate --must-reset
```

--------------------------------

### Bypass Onboarding Gate with Docker Compose

Source: https://github.com/zimengxiong/excalidash/blob/main/README.md

Temporarily bypass the onboarding gate for emergency operator access by setting the DISABLE_ONBOARDING_GATE environment variable.

```bash
DISABLE_ONBOARDING_GATE=true docker compose -f docker-compose.prod.yml up -d
```