Purpose: This document describes the Docker deployment architecture for Prompt Optimizer, covering container structure, configuration options, service routing, and deployment procedures. Docker deployment provides a self-contained environment that hosts both the web application and the MCP server behind Nginx.
For Vercel static hosting deployment, see Vercel Deployment. For desktop application distribution, see Desktop Distribution. For detailed environment configuration across all platforms, see Environment Configuration and API Keys.
The Docker container bundles three main components: the static web application, the MCP server, and Nginx as the reverse proxy. All components are initialized through scripts during container startup.
Diagram: Docker Container Structure
Sources: README.md111-156 docker-compose.yml1-44 docker/generate-auth.sh1-46
Nginx serves as the entry point for all HTTP traffic, handling both static file serving and reverse proxying to the MCP server. The configuration is dynamically generated at container startup.
Key routing rules:
/: Serves static files from /usr/share/nginx/html (the compiled web application)/mcp: Proxies requests to http://localhost:3000 (the MCP server process)ACCESS_PASSWORD is set via auth.conf inclusionThe generate-auth.sh script docker/generate-auth.sh1-46 executes during container initialization to create authentication configuration. It generates /etc/nginx/conf.d/auth.conf and /etc/nginx/auth/.htpasswd if credentials are provided.
The web application is a pre-built Vue 3 single-page application located at /usr/share/nginx/html. During container startup, environment variables prefixed with VITE_ are injected into the static JavaScript files, enabling runtime configuration without rebuilding.
Environment variable injection: A startup script (typically env-replace.sh) searches for placeholder patterns in the compiled JavaScript and replaces them with actual environment variable values. This allows API keys and base URLs to be configured at deployment time.
The MCP server runs as a separate Node.js process listening on port 3000 inside the container. It provides three optimization tools accessible via the Model Context Protocol over HTTP.
Available tools:
optimize-user-prompt: Optimizes user-facing promptsoptimize-system-prompt: Optimizes system-level instructionsiterate-prompt: Performs iterative refinement on existing promptsThe server requires at least one AI provider API key (e.g., VITE_OPENAI_API_KEY) to function. For detailed MCP server configuration and usage, see MCP Server Integration.
Sources: README.md182-246 docker-compose.yml31-35
The simplest deployment method uses docker run with environment variables passed via -e flags.
Basic deployment (no authentication):
Deployment with API keys and authentication:
Chinese mirror (for users in mainland China):
Sources: README.md111-130 README_EN.md112-127
Docker Compose provides declarative configuration management through YAML files, making it easier to manage complex deployments with multiple environment variables.
Diagram: Docker Compose Configuration Structure
Sources: README.md132-180 docker-compose.yml1-44
Standard deployment using docker-compose.yml docker-compose.yml1-44:
Development deployment using docker-compose.dev.yml docker-compose.dev.yml1-37:
The development variant includes:
extra_hosts configuration for accessing host services (e.g., local Ollama).env.local fileThe Docker container accepts environment variables in three categories: web application configuration, MCP server settings, and access control.
Diagram: Environment Variable Flow
Sources: docker-compose.yml18-41
These variables configure API keys and endpoints for AI service providers. They are injected into the static web application at container startup.
Primary provider keys:
VITE_OPENAI_API_KEY: OpenAI API keyVITE_GEMINI_API_KEY: Google Gemini API keyVITE_DEEPSEEK_API_KEY: DeepSeek API keyVITE_SILICONFLOW_API_KEY: SiliconFlow API keyVITE_ZHIPU_API_KEY: Zhipu AI API key (not shown in compose file but supported)Custom provider configuration:
VITE_CUSTOM_API_KEY: API key for custom OpenAI-compatible endpointsVITE_CUSTOM_API_BASE_URL: Base URL for custom providerVITE_CUSTOM_API_MODEL: Model identifier for custom providerFor configuring multiple custom models with different identifiers, see Environment Configuration and API Keys.
These configure the behavior of the Model Context Protocol server.
MCP_DEFAULT_MODEL_PROVIDER: Default AI provider (openai, gemini, deepseek, siliconflow, zhipu, custom)MCP_LOG_LEVEL: Logging verbosity (info, debug, warn, error)MCP_DEFAULT_LANGUAGE: Default language for responses (zh, en)Note: The MCP_HTTP_PORT variable is ignored in Docker deployments. The MCP server always listens on port 3000 internally, with external access configured through Nginx port mapping.
Sources: docker-compose.yml31-35 README.md190-202
These enable HTTP Basic Authentication for the entire application.
ACCESS_USERNAME: Username for Basic Auth (default: admin)ACCESS_PASSWORD: Password for Basic Auth (if not set, authentication is disabled)When ACCESS_PASSWORD is set, the generate-auth.sh script docker/generate-auth.sh1-46 executes during container startup:
/etc/nginx/auth/ directory/etc/nginx/auth/.htpasswd using htpasswd command docker/generate-auth.sh25/etc/nginx/conf.d/auth.conf with auth_basic directives docker/generate-auth.sh31-35If ACCESS_PASSWORD is empty or unset, authentication is disabled by writing auth_basic off; to the configuration file docker/generate-auth.sh9-14
Sources: docker/generate-auth.sh1-46 docker-compose.yml39-41
NGINX_PORT: Internal port for Nginx (default: 80). Used in health checks and internal routing. The external port is configured via Docker's port mapping (-p flag or ports: in Compose).The Nginx configuration implements path-based routing to separate the web UI from the MCP server endpoint.
Table: Request Routing Rules
| Request Path | Destination | Purpose | Authentication |
|---|---|---|---|
/ | Static files in /usr/share/nginx/html | Web application UI | Applied if configured |
/assets/* | Static files | JavaScript, CSS, images | Applied if configured |
/mcp | http://localhost:3000 (MCP server) | MCP protocol endpoint | Applied if configured |
/mcp/* | http://localhost:3000/* | MCP API routes | Applied if configured |
Example access URLs (assuming container port 80 mapped to host port 8081):
http://localhost:8081/http://localhost:8081/mcpSources: README.md152-154
When running in Docker, the MCP server is automatically started and accessible through the /mcp path. External MCP clients (like Claude Desktop) can connect using the Nginx-exposed URL.
Claude Desktop configuration example README.md216-236:
This configuration file should be placed in Claude Desktop's service directory:
%APPDATA%\Claude\services\services.json~/Library/Application Support/Claude/services/services.json~/.config/Claude/services/services.jsonFor complete MCP server documentation, including tool descriptions and usage examples, see MCP Server Integration.
Sources: README.md182-246
Docker Compose configurations include health checks to verify both the web application and MCP server are functioning.
Health check configuration docker-compose.yml12-17:
Health check behavior:
/ (web UI) and /mcp (MCP server)The container is marked unhealthy if either endpoint fails to respond. This status can be viewed with docker ps or docker compose ps.
Sources: docker-compose.yml12-17
Prompt Optimizer Docker images are distributed through two registries to accommodate different geographic regions.
Available registries:
linshen/prompt-optimizer:latestregistry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer:latestImage tags:
latest: Latest stable releasedev: Development builds (when building from source with docker-compose.dev.yml)Selecting a registry:
For users in mainland China with slow Docker Hub access, modify the image reference in docker-compose.yml docker-compose.yml3:
Or when using docker run, replace the image name directly README.md130:
Sources: README.md130 docker-compose.yml3 README_EN.md112-127
Standard port mappings:
docker-compose.yml): Host port 28081 → Container port 80 docker-compose.yml11docker-compose.dev.yml): Host port 28082 → Container port 80 docker-compose.dev.yml11-p flag (commonly 8081:80)Internal ports:
NGINX_PORT (default 80)3000 inside the containerSecurity note: The NGINX_PORT variable docker-compose.yml20 only affects the internal container configuration. External exposure is controlled by Docker's port mapping, allowing you to bind to any available host port without modifying the application.
Sources: docker-compose.yml11 docker-compose.yml20 docker-compose.dev.yml11
Table: Deployment Mode Comparison
| Aspect | Production (docker-compose.yml) | Development (docker-compose.dev.yml) |
|---|---|---|
| Image source | Pre-built from Docker Hub | Built from local source |
| Build trigger | None (uses published image) | Builds via dockerfile: Dockerfile |
| Port mapping | 28081:80 | 28082:80 |
| Environment file | Inline environment variables | .env.local file |
| Host access | Not configured | host.docker.internal available |
| Use case | Stable deployments, quick setup | Local development, testing changes |
Development deployment advantages docker-compose.dev.yml12-13:
extra_hosts configuration allows the container to access services running on the host machine (e.g., local Ollama instances) via host.docker.internal.env.local for development-specific configurationRefresh this wiki