Skip to main content

DirectAdmin FTPS Deployment Protocol Documentation (deploy_production.py)

📜 Overview and Purpose​

This document details the operational protocol executed by deploy_production.py, an automated script designed to manage secure, high-availability file transfers for DirectAdmin hosting environments using FTPS (FTP over TLS/SSL). The primary goal is to ensure that deployments are atomic, secure, efficient, and adhere to modern web development best practices regarding content delivery and security hardening.

The protocol mandates the use of Explicit TLS encryption on port 21 and utilizes passive mode for data transfer channels.

⚙️ I. Technical Protocol Specification (FTPS Configuration)​

A. Core Connectivity Requirements​

ComponentDetailRequirementNotes
ProtocolFTPS (FTP over TLS/SSL)MandatoryEnsures all data and credentials are encrypted.
Control PortTCP 21Explicit TLS (AUTH TLS)The initial connection must negotiate encryption on this port.
Data Transfer ModePassive Mode (PASV)MandatoryPrevents firewall issues associated with opening multiple ports for the data channel.
Server SoftwareProFTPD / Pure-FTPdConfigured for TLS/SSLMust be configured to handle explicit TLS negotiation and passive mode ranges.

B. Server Configuration Directives (ProFTPD/Pure-FTPd)​

The deployment script assumes the following directives are correctly implemented on the target server:

  1. TLS Enforcement:
    • Require SSL: All connections must be upgraded to TLS immediately upon connection establishment.
    • Explicit TLS Requirement: The client must issue AUTH TLS before any data transfer occurs.
  2. Passive Port Range:
    • The server must open a defined, non-standard port range (e.g., 50000–51000) for passive data connections. This range must be correctly configured in the firewall (iptables/firewalld) and within the FTP daemon configuration.

🛡️ II. Deployment Mechanics and Security Guardrails​

A. Diff-Only Uploads (Delta Transfer)​

The script does not perform full directory synchronization unless explicitly required (e.g., initial setup). Instead, it implements a diff-only upload mechanism to minimize bandwidth usage and deployment time.

  1. Process: The script compares the contents of the local source repository (SOURCE_DIR) against the remote target directory (TARGET_DIR).
  2. Action: Only files that have been modified (based on timestamp or checksum) or are new are transferred.
  3. Efficiency: This significantly reduces data transfer volume, making deployments faster and more resilient to network interruptions.

B. Security Guardrails​

The following security measures are enforced during the deployment process:

  1. File Permissions: All uploaded files must adhere to strict permissions (e.g., 644 for assets, 755 for directories). The script explicitly prevents the upload of executable scripts or binaries into public-facing asset folders unless absolutely necessary and whitelisted.
  2. Root Directory Traversal Prevention: The deployment process strictly enforces that all uploads occur within the designated web root (/var/www/html). Any attempt to write outside this directory (e.g., attempting to traverse up using ../) is blocked by the script's file system checks and the underlying FTP user permissions.
  3. Credential Handling: Credentials are never stored in plain text within the deployment logs or source code. They are managed via secure environment variables or secrets management systems.

⚠️ III. Operational Pitfalls and Best Practices​

The following pitfalls must be addressed during pre-deployment setup and post-deployment validation to ensure a stable production environment.

A. Sub-Directory Traversal (CWD Requirements)​

Pitfall: If the deployment script assumes that all files are placed directly into the root of the web directory, but the source repository structure includes subdirectories (e.g., assets/js, templates/header), a simple copy operation will fail or place assets in the wrong location.

Requirement: The deployment process must maintain contextual awareness. When uploading files from SOURCE_DIR/assets/ to TARGET_DIR/, the script must ensure that the target directory structure (TARGET_DIR/assets/) is created before the file transfer occurs, maintaining the relative path integrity.

B. Default Index File Management (Index.html Removal)​

Pitfall: Many CMS or framework deployments include a default index.html or placeholder page left by the development environment. If this file is not explicitly removed, it can cause confusion for users and may mask actual application errors.

Best Practice: The deployment script must include an atomic step to identify and remove any pre-existing, non-application-specific default index files (index.html, default.php) from the root of the target directory before the new content is uploaded. This ensures that only the intended application entry point is served.

C. Asset Cache-Busting (Cache Invalidation)​

Pitfall: When assets (CSS, JavaScript images) are updated, browsers and CDNs often cache the old versions aggressively, meaning users may continue to see outdated styles or functionality even after a successful deployment.

Requirement: The deployment protocol must incorporate cache-busting techniques. This is typically achieved by:

  1. Versioned Filenames: Appending a unique hash or version number to asset filenames (e.g., styles.v20231027.css).
  2. Manifest Update: Updating the main application template/manifest file (e.g., site.js) with these new, versioned paths after all assets have been successfully uploaded.