Docker Deployment Strategies
Relevant source files
The following files were used as context for generating this wiki page:
Docker deployment strategies in the freebuff-proxy project focus on providing an ultra-lightweight, high-performance runtime based on node:22-alpine. The strategy prioritizes minimal configuration overhead, host-level networking for optimal proxy performance, and strict data persistence. The deployment is designed to be "zero-config" for the user, where almost all operational changes occur through the web console rather than manual file editing.
Sources: CLAUDE.md:36-39, README_EN.md:38-40
Container Architecture and Runtime
The deployment utilizes a minimal image containing only the Node.js 22 runtime and two production dependencies: undici and yaml. This results in an image size of a few dozen megabytes. The system runs TypeScript source files directly using Node 22 without a transpilation or bundling step, ensuring the container environment matches the development environment exactly.
Sources: CLAUDE.md:36-39, README_EN.md:38-41
Networking Strategy
The project enforces network_mode: host for production deployments. In this mode, the container shares the host's network stack directly. This avoids the overhead of Docker's virtual bridge and NAT, which is critical for proxy performance.
- Port Mapping: You must not use the
portsdirective indocker-compose.ymlbecause it is ignored in host mode. - Listening: The application listens on
0.0.0.0at the port specified by theFREEBUFF_PROXY_PORTenvironment variable (defaulting to 8787). - Proxy Access: To connect the proxy to local tools on the host, use
http://127.0.0.1:<port>.
Sources: CLAUDE.md:43-46, README_EN.md:52-54
Data Persistence
All application data, including credentials, user lists, and proxy settings, resides in the /data directory inside the container. You must mount this to a persistent volume on the host (typically ./data) to ensure data survives container restarts or image upgrades.
Sources: CLAUDE.md:52, README_EN.md:88-93
Deployment Workflow
The following flowchart illustrates the standard deployment and update lifecycle for the proxy service.
Sources: README_EN.md:44-51, README.md:50-57
Configuration Management
The deployment strategy minimizes manual configuration. While config.yaml exists, it serves as a fallback for default values. The single source of truth for most settings is the web console, which writes directly to JSON files in the persistent data volume.
Hardcoded Upstream Safety
The upstream API base (https://www.codebuff.com) is hardcoded within the source to prevent deployment failures caused by incorrect URL entries in configuration templates (e.g., missing "www"). This ensures that new containers always connect to the correct endpoint regardless of local configuration file state.
Sources: scripts/check-config-consistency.ts:1-20
Environment Variables
Environment variables are used primarily for bootstrap settings and container behavior.
| Variable | Purpose | Default |
|---|---|---|
ADMIN_PASSWORD | Sets the initial administrator password. | Randomly generated if unset |
FREEBUFF_PROXY_PORT | The port the service listens on inside the container. | 8787 |
FREEBUFF_PROXY_DATA_DIR | Internal path for data storage. | /data |
FREEBUFF_UPSTREAM_API_BASE | Overrides the hardcoded upstream (for testing only). | https://www.codebuff.com |
Sources: README_EN.md:46, 126, scripts/ci/pipeline/lib/container.ts:25-30
Continuous Integration and Delivery (CI/CD)
The deployment cycle is supported by a CI pipeline that manages versioning and image metadata.
Version Injection
During the Docker build process, the system executes scripts/release/inject-version.ts. This script reads the Git tag or version from package.json and generates a dashboard/version.json file. This ensures the web interface correctly reports the deployed version, even if built in a headless CI environment.
Sources: scripts/release/inject-version.ts:1-20
Pipeline Testing
The project includes a pipeline for testing container images. This pipeline automates the following sequence:
- Building the local image.
- Synthesizing a baseline data source.
- Starting a test container with isolated ports and volumes.
- Executing scenarios against the running container to verify health and connectivity.
Sources: scripts/ci/pipeline/run.ts:15-35, scripts/ci/pipeline/lib/container.ts:20-40
Conclusion
The freebuff-proxy Docker strategy emphasizes a "set and forget" approach. By leveraging network_mode: host, node:22-alpine, and a unified /data persistence layer, the project ensures high performance and reliability with minimal maintenance. Developers and users interact with the system primarily through the web interface, while the underlying Docker infrastructure handles the complexities of proxy networking and environment isolation.