Deployment and Configuration

Relevant source files

• .github/workflows/docker.yml
• .github/workflows/release.yml
• .github/workflows/test.yml
• README.md
• README_EN.md
• docker-compose.yml
• docs/archives/116-desktop-packaging-optimization/README.md
• docs/testing/README.md
• docs/testing/vcr-usage-guide.md
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• docs/workspace/architecture-migration-analysis.md
• docs/workspace/testing-redesign/architecture.md
• docs/workspace/testing-redesign/findings.md
• docs/workspace/testing-redesign/progress.md
• docs/workspace/testing-redesign/task_plan.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• packages/core/src/services/model/defaults.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/mcp-server/src/config/models.ts
• vercel.json

Purpose and Scope

This document describes the deployment architecture, configuration options, and security considerations for production deployments of the Prompt Optimizer system. It covers four primary deployment targets: Docker (with bundled MCP server), Vercel (web-only), Desktop applications (Electron), and Chrome Extension. For information about the development workflow and build system, see Development Workflow and Build System. For details about the MCP server integration and client configuration, see MCP Server Integration.

---

Deployment Targets Overview

The system provides four distinct deployment pathways, each with specific build processes and configuration requirements.

Deployment Pipeline Diagram

Sources: README.md73-246 README_EN.md73-249 .github/workflows/release.yml1-670 .github/workflows/docker.yml1-71

Deployment Target Characteristics

Target	Runtime Environment	Storage Backend	CORS Restrictions	Auto-Update
Vercel/Web	Browser (HTTPS)	IndexedDB via Dexie	Yes (HTTPS mixed content)	N/A (always latest)
Docker	Nginx + Node.js	JSON files (volume)	Yes (browser client)	N/A (image versioning)
Desktop	Electron (sandboxed renderer + Node.js main)	JSON files (userData)	No (main process bypass)	Yes (via electron-updater)
Extension	Chrome Extension (Manifest V3)	chrome.storage.local	Partially relaxed	Via Chrome Web Store

Sources: README.md96-110 README_EN.md96-106 docker-compose.yml1-44

---

Docker Deployment Architecture

Docker deployment bundles both the web application and MCP server into a single container, using Nginx for HTTP routing and basic authentication.

Docker Container Internal Architecture

Sources: docker-compose.yml1-44 docs/user/mcp-server.md13-32 docs/user/mcp-server_en.md13-28

Docker Compose Configuration

The docker-compose.yml file defines the service structure and environment variable mappings:

docker-compose.yml1-44

Key Configuration Elements:

• Image Source: linshen/prompt-optimizer:latest (Docker Hub) or registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer:latest (Aliyun mirror)
• Port Mapping: 28081:80 (host:container) - Nginx internal port configurable via NGINX_PORT
• Health Check: Validates both web app (/) and MCP server (/mcp) endpoints
• Security Options: no-new-privileges:true enforces container privilege restrictions

Environment Variables

Docker deployment requires two categories of environment variables:

Web Application API Keys (used by frontend):

MCP Server Configuration:

Access Control (optional):

Sources: docker-compose.yml19-42 env.local.example1-147

Multi-Registry Docker Build

The Docker build workflow pushes images to both Docker Hub and Aliyun Container Registry:

.github/workflows/docker.yml10-70

Build Process:

1. Triggers on successful test.yml workflow completion (main/master branch)
2. Builds multi-architecture images (linux/amd64, linux/arm64)
3. Tags with both version number and latest
4. Pushes simultaneously to both registries

Sources: .github/workflows/docker.yml1-71

---

Vercel Deployment Configuration

Vercel deployment targets the web application only (no MCP server) and requires specific build configuration to handle the monorepo structure.

Vercel Build Configuration

vercel.json1-32

Key Configuration Elements:

Field	Purpose	Value
buildCommand	Handles monorepo builds, copies web dist to extension package	Conditional pnpm build with dist copying
outputDirectory	Specifies built static files location	packages/web/dist
installCommand	Installs dependencies and Vercel analytics	pnpm install && pnpm i @vercel/analytics -w
rewrites	SPA routing fallback	All routes → /index.html except /api/*
github.silent	Suppresses verbose GitHub comments	true
git.deploymentEnabled	Auto-deploys from main/master	{"main": true, "master": true}

Deployment Triggers:

• Automatic: Push to main or master branch
• Manual: Vercel dashboard or CLI
• One-click:

Sources: vercel.json1-32 README.md82-95 README_EN.md82-94

Environment Variables:

Vercel environment variables follow the same VITE_* prefix pattern as Docker but are configured through the Vercel dashboard or .env files:

Sources: vercel.json24-32 README.md89-95 docs/user/deployment/vercel.md1-95

---

Desktop Application Distribution

Desktop applications are built and released via GitHub Actions when a version tag is pushed. The workflow supports Windows, macOS (Intel + Apple Silicon), and Linux platforms.

Release Workflow Architecture

Sources: .github/workflows/release.yml1-670

Dynamic Package.json Configuration

Before building, the workflow dynamically modifies packages/desktop/package.json to inject version, repository URL, and publish configuration:

.github/workflows/release.yml44-114

Configuration Steps:

1. Extract version from Git tag (removing v prefix)
2. Set repository.url to current GitHub repository
3. Parse repository owner/name from ${{ github.repository }}
4. Detect version type (release/prerelease/hotfix) via regex
5. Configure build.publish for electron-updater:

Sources: .github/workflows/release.yml44-241

Artifact Naming Convention

All build artifacts follow a consistent naming pattern:

PromptOptimizer-{version}-{os}-{arch}.{ext}

Examples:

• Windows: PromptOptimizer-1.4.0-win-x64.exe
• macOS Intel: PromptOptimizer-1.4.0-darwin-x64.dmg
• macOS Apple Silicon: PromptOptimizer-1.4.0-darwin-arm64.dmg
• Linux: PromptOptimizer-1.4.0-linux-x86_64.AppImage

Portable Versions (ZIP archives):

• Windows: PromptOptimizer-1.4.0-win-x64.zip
• macOS: PromptOptimizer-1.4.0-darwin-arm64.zip
• Linux: PromptOptimizer-1.4.0-linux-x64.zip

Sources: .github/workflows/release.yml39-50 README.md97-100

Auto-Updater Configuration

Desktop installers (.exe, .dmg, .AppImage) support automatic updates via electron-updater. The workflow generates update manifest files (.yml) alongside each build:

Manifest Files:

• latest.yml (Windows)
• latest-mac.yml (macOS)
• latest-linux.yml (Linux)

Update Mechanism:

1. Application checks GitHub Releases on startup
2. Compares current version with latest release
3. Downloads delta or full update
4. Prompts user to restart

Requirements:

• GH_TOKEN secret must be configured (read-only GitHub token)
• Repository must be public (private: false in publish config)
• Release must not be draft

Sources: .github/workflows/release.yml98-122 .github/workflows/release.yml246-249

Release Notes Generation

The create-release job automatically generates comprehensive release notes:

.github/workflows/release.yml477-651

Release Notes Include:

• Version type badge (stable/prerelease/hotfix)
• Download links for all platforms
• Platform-specific installation instructions
• Commit history since last release (max 20 commits)
• Contributors list (excluding main authors and bots)
• macOS security warning for unsigned apps

Sources: .github/workflows/release.yml477-670

---

Environment Configuration and API Keys

The system uses a centralized environment variable mapping defined in packages/core/src/services/model/defaults.ts.

Provider Environment Variable Mapping

packages/core/src/services/model/defaults.ts7-21

Standard Providers:

• OpenAI: VITE_OPENAI_API_KEY
• Gemini: VITE_GEMINI_API_KEY
• Anthropic: VITE_ANTHROPIC_API_KEY
• DeepSeek: VITE_DEEPSEEK_API_KEY
• SiliconFlow: VITE_SILICONFLOW_API_KEY
• Zhipu: VITE_ZHIPU_API_KEY
• DashScope: VITE_DASHSCOPE_API_KEY
• OpenRouter: VITE_OPENROUTER_API_KEY
• ModelScope: VITE_MODELSCOPE_API_KEY

Custom Provider (single instance):

Sources: packages/core/src/services/model/defaults.ts7-96

Multi-Custom Model Configuration

The system supports unlimited custom models via suffix pattern:

Requirements:

• All three variables (KEY, BASE_URL, MODEL) must be present
• Suffix becomes model display name (e.g., qwen3 → "Qwen3")
• Suffix must not contain dots, spaces, or special symbols

Dynamic Model Generation:

packages/core/src/services/model/model-utils.ts1-149 contains the logic to scan environment variables and generate TextModelConfig instances for each detected custom model.

Sources: env.local.example42-71 packages/core/src/services/model/defaults.ts98-115

MCP Server Specific Configuration

MCP server requires additional environment variables when deployed standalone or in Docker:

Provider Selection Logic:

packages/mcp-server/src/config/models.ts12-66

The setupDefaultModel function:

1. Imports defaultModels from core (includes all enabled providers)
2. Filters to enabled models only
3. Matches MCP_DEFAULT_MODEL_PROVIDER against:
   • Model key (e.g., custom_qwen3)
   • Provider ID (e.g., openai)
   • Provider name (case-insensitive)
4. Falls back to first available model if no match
5. Creates internal mcp-default model key in ModelManager

Sources: packages/mcp-server/src/config/models.ts1-69 env.local.example72-91

Configuration File Structure

The env.local.example file serves as the canonical reference for all environment variables:

env.local.example1-147

Sections:

1. LLM API Keys (lines 4-36)
2. Multi-Custom Models (lines 42-71)
3. MCP Server Config (lines 72-91)
4. Docker Access Control (lines 92-100)
5. Dev Environment Auto-Update (lines 101-110)
6. Usage Instructions (lines 111-147)

Sources: env.local.example1-147

---

Security Architecture and CORS Handling

The system implements different security models depending on the deployment target, with CORS restrictions being the primary architectural concern.

Security Model by Platform

Sources: README.md350-408 README_EN.md350-410

CORS Restrictions and Mitigation

Problem Statement:

The system is a pure frontend application that makes direct API calls to LLM providers. Browsers enforce CORS (Cross-Origin Resource Sharing) policies that block many API endpoints.

CORS Issues by Scenario:

Scenario	Issue	Solution
Online Web (HTTPS)	Cannot call local HTTP APIs (Ollama) due to mixed content policy	Use Desktop app or deploy via HTTP (Docker)
Web/Extension	Cannot call CORS-restricted commercial APIs (Nvidia DS API, Volcano API)	Use Desktop app or API proxy service (OneAPI/NewAPI)
Vercel/Docker Web	Browser still enforces CORS regardless of server deployment	Desktop app bypasses entirely via Node.js

Desktop Application CORS Bypass:

Desktop applications run core services in the Electron main process, which has full Node.js capabilities:

User Action (Renderer)
    ↓ IPC call via contextBridge
Main Process (Node.js)
    ↓ Direct HTTP request (no CORS)
LLM API
    ↓ Response
Main Process
    ↓ IPC response
Renderer (Update UI)

Electron Proxy Classes:

• ElectronLLMProxy: Proxies LLMService calls from renderer to main
• ElectronModelManagerProxy: Proxies ModelManager operations
• All proxies use electronAPI exposed via contextBridge

Sources: README.md361-379 README_EN.md361-382

Docker Basic Authentication

Docker deployment supports optional HTTP Basic Authentication for web access:

Nginx Configuration:

• Authentication applies to all routes except /mcp
• MCP route exempt to support MCP protocol (which doesn't support Basic Auth)
• Username/password validated before serving web app

MCP Route Exception:

docs/user/mcp-server.md169-183 describes the authentication exemption:

This was added in v1.4.0+ to fix 401 errors when MCP clients (Claude Desktop) attempted to connect.

Sources: docker-compose.yml39-42 docs/user/mcp-server.md169-183 docs/user/mcp-server_en.md186-203

Electron Context Isolation

Desktop applications enforce strict context isolation for security:

Architecture:

1. Renderer Process: Sandboxed browser context, no Node.js access
2. Preload Script: Bridge layer using contextBridge API
3. Main Process: Full Node.js access, handles all file/network operations

Security Guarantees:

• Renderer cannot directly access Node.js APIs
• Renderer cannot access main process memory
• Only whitelisted APIs exposed via electronAPI
• IPC messages validated before execution

Exposed APIs (via contextBridge):

Sources: README.md102-105 README_EN.md102-105

Recommended Deployment Patterns

For Maximum Security:

1. Use Desktop application (no CORS, local storage, offline capable)
2. Configure API keys via UI Model Manager (not environment variables)
3. Enable auto-updates for security patches

For Team/Production Use:

1. Deploy via Docker with ACCESS_PASSWORD set
2. Use HTTPS reverse proxy (Nginx, Caddy, Traefik)
3. Mount Docker volumes for data persistence
4. Deploy API proxy service (OneAPI/NewAPI) if calling CORS-restricted endpoints

For Public Demo/Testing:

1. Deploy to Vercel (free, auto-scaling)
2. Do NOT commit API keys to repository
3. Use Vercel environment variables for API keys
4. Consider rate limiting at provider level

Sources: README.md366-379 README_EN.md366-382 docs/user/deployment/vercel.md1-95