Docker Deployment & Compose

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• warpgate/src/commands/setup.rs
• warpgate/Cargo.toml
• warpgate-core/Cargo.toml
• warpgate-common/Cargo.toml

Warpgate is designed to be deployed as a containerized bastion host, facilitating secure access to SSH, HTTPS, MySQL, and PostgreSQL targets within a network. In a Docker environment, Warpgate typically resides in a DMZ or a peripheral network layer, acting as a gateway that receives external connections, authenticates users, and proxies traffic to internal resources.

The Docker deployment model emphasizes a "single binary" philosophy within the container, utilizing safe Rust for the backend and a Svelte-based web interface for administration. When running under Docker, the application adapts its setup process to utilize standard container paths and environment variables for configuration.

Sources: README.md:1-25, warpgate/src/commands/setup.rs:104-106

Container Architecture and Environment

When Warpgate detects it is running within a Docker container, it modifies its default behavior to align with containerized best practices. This includes pre-defining data paths and enabling protocol listeners by default during the initial setup phase.

Path Mapping and Persistence

For Docker deployments, the application expects a persistent volume to be mounted at /data. This directory is used to store all stateful information, including the SQLite database, TLS certificates, SSH host keys, and session recordings.

The diagram above illustrates the relationship between the host system's persistent storage and the internal directory structure expected by the Warpgate container.

Sources: warpgate/src/commands/setup.rs:101-115, warpgate/src/commands/setup.rs:198-202

Automated Configuration (Unattended Setup)

The application supports an unattended setup mode, which is particularly useful for automated Docker deployments using environment variables or CLI flags. This mode allows the initialization of the admin password and protocol ports without interactive terminal prompts.

Variable/Option	Description	Default in Docker
data_path	Base directory for app data	/data
WARPGATE_ADMIN_PASSWORD	Environment variable for the initial admin password	Required if not in CLI
http_port	Port for the Web Admin and HTTP proxy	Defined by setup
ssh_port	Port for SSH bastion connections	Enabled by default
mysql_port	Port for MySQL proxy connections	Enabled by default
postgres_port	Port for PostgreSQL proxy connections	Enabled by default

Sources: warpgate/src/commands/setup.rs:101-105, warpgate/src/commands/setup.rs:218-232

Deployment Workflow

The deployment of Warpgate via Docker generally follows a two-step process: initialization (setup) and execution (run).

Initialization Sequence

Before the service starts, a configuration file must be generated. In a Docker context, this is often handled by running the setup command with volume mounts.

During setup in a Docker environment, the application automatically enables SSH, MySQL, and PostgreSQL listeners unless specified otherwise, assuming these will be routed via Docker port mapping.

Sources: warpgate/src/commands/setup.rs:125-180, warpgate/src/commands/setup.rs:321-325

Execution Command

Once configured, the container is started using the run command. The standard deployment command exposes the administrative web interface and the SSH bastion port.

docker run -d \
  -p 8888:8888 \
  -p 2222:2222 \
  -v /path/to/your/data:/data \
  ghcr.io/warp-tech/warpgate

Sources: README.md:88-90, warpgate/src/commands/setup.rs:326-328

Protocol Listening & Networking

In Docker deployments, Warpgate listens on Ipv6Addr::UNSPECIFIED (dual-stack ::) to ensure it can receive traffic forwarded by the Docker proxy from the host's network interfaces.

Port Configuration during Setup

The setup logic defaults to the following behavior when is_docker() returns true:

1. HTTP/Admin: Listens on the specified HTTP port (default often 8888).
2. SSH: Automatically enabled on the standard Warpgate SSH port (default 2222).
3. MySQL/PostgreSQL: Automatically enabled to allow proxying database traffic.

Sources: warpgate/src/commands/setup.rs:141-180

Security and Compliance

The Docker image is built upon a stack of safe Rust libraries. Security configuration within the container includes:

• Secure File Permissions: The application explicitly calls secure_directory and secure_file on sensitive assets like the database and private keys during the setup phase.
• Dependency Auditing: The project uses deny.toml to audit and ban insecure dependencies (e.g., openssl-sys is denied in favor of rustls).
• TLS Termination: Warpgate generates its own self-signed certificates during setup if none are provided, ensuring that even the initial web admin access is encrypted.

Sources: deny.toml:104-106, warpgate/src/commands/setup.rs:118-120, warpgate/src/commands/setup.rs:298-312

Summary

Docker deployment provides a streamlined method for hosting the Warpgate bastion. By mounting /data, users ensure persistence of the SQLite database and session recordings. The application's internal logic detects the Docker environment to simplify the setup process, favoring automated pathing and broad protocol enablement while maintaining strict file-level security for sensitive credentials and keys.

Sources: README.md:40-55, warpgate/src/commands/setup.rs:104-115