ForgeDeployment

ForgeDeployment

Complete deployment automation system for Forge applications. Deploy to cloud providers with automated provisioning, rollback capabilities, and zero-downtime deployments.

Overview

ForgeDeployment automates the entire deployment pipeline from server creation to production deployment. It solves the complexity of cloud infrastructure management by providing automated provisioning, configuration, and deployment coordination.

Problems Solved

  • Manual Server Setup: Automated cloud provider integration eliminates manual server configuration
  • Deployment Downtime: Zero-downtime deployments with rollback capabilities
  • SSL Management: Automated Let's Encrypt certificate generation and renewal
  • Infrastructure as Code: Declarative configuration for reproducible deployments
  • Multi-Provider Support: Extensible provider system for different cloud platforms

Key Features

Automated Provisioning

  • DigitalOcean provider integration
  • Custom provider extensibility
  • SSH key management
  • System installation (PHP, Nginx, Database)
  • Environment-specific configurations

Deployment Management

  • Incremental project uploads
  • Deployment state tracking
  • Automatic rollback capabilities
  • Git diff verification
  • Zero-downtime deployments

Security & SSL

  • Let's Encrypt integration
  • Custom SSL certificate support
  • Automatic DNS configuration
  • Secure SSH key handling
  • Production environment safeguards

Monitoring & Logging

  • Real-time deployment status
  • Detailed deployment logs
  • Progress tracking with steps
  • Hub dashboard integration
  • Production environment detection

Architecture

graph TD
    A[Deployment Controller] --> B[Deployment Hub Service]
    B --> C[Deployment Execution Service]
    B --> D[Provider Interface]
    B --> E[Configuration Reader]
    B --> F[State Service]
    C --> G[Provisioners]
    C --> H[SSH Service]
    D --> I[DigitalOcean Provider]
    D --> J[Custom Providers]
    F --> K[Deployment State]
    E --> L[Deployment Config]
    
    style A fill:#e5e7eb
    style B fill:#3b82f6
    style C fill:#10b981
    style D fill:#f59e0b
    style E fill:#ef4444
    style F fill:#8b5cf6
    style G fill:#6366f1
    style H fill:#ec4899
    style I fill:#3b82f6
    style J fill:#06b6d4
    style K fill:#8b5cf6
    style L fill:#ef4444

Provider Abstraction

Extensible provider system allows adding new cloud providers through a simple interface.

  • DigitalOcean provider included
  • Custom providers via ProviderInterface
  • Provider-specific configuration management
  • API key and credential handling

State Management

Complete deployment state tracking with validation and recovery capabilities.

  • Step-by-step progress tracking
  • State validation and recovery
  • Resume interrupted deployments
  • Rollback point management

Cloud Providers

DigitalOcean

Full-featured provider for DigitalOcean cloud platform.

  • Droplet creation and management
  • SSH key provisioning
  • Firewall configuration
  • Domain management
  • Resource monitoring

Custom Providers

Extensible system for adding your own cloud providers.

  • Implement ProviderInterface
  • Custom provisioning logic
  • Provider-specific configurations
  • Plugin architecture

CLI Commands

Deployment Commands

# Full deployment wizard
forge-deployment:deploy

# With specific provider
forge-deployment:deploy --provider=digitalocean

# With custom config
forge-deployment:deploy --config=./deployment.php

# With SSH key
forge-deployment:deploy --ssh-key=~/.ssh/id_rsa.pub
  • Interactive deployment wizard
  • Resume interrupted deployments
  • Provider selection and configuration
  • SSH key management

Management Commands

# Server management
forge-deployment:create-server
forge-deployment:delete-server
forge-deployment:configure-dns

# Deployment management
forge-deployment:deploy-env
forge-deployment:rollback
forge-deployment:resume
forge-deployment:status
forge-deployment:update

# SSL and security
forge-deployment:setup-ssl
forge-deployment:fix-permissions

# Configuration
forge-deployment:init-deployment-config

Core Services

Deployment Services

DeploymentHubService
├── State management
├── Configuration handling  
├── Progress tracking
└── Logging coordination

DeploymentExecutionService
├── Provider orchestration
├── Provisioning coordination
├── Upload automation
└── Rollback management

Support Services

SshService
├── Connection management
├── Command execution
└── Key handling

LetsEncryptService  
├── Certificate generation
├── DNS configuration
└── Auto-renewal

CloudflareService
├── DNS management
├── SSL management
└── API integration

Configuration

// deployment.php - Complete deployment configuration
return [
    'provider' => 'digitalocean',
    'server' => [
        'name' => 'my-app-server',
        'region' => 'nyc3',
        'size' => 's-2vcpu-4gb',
        'image' => 'ubuntu-22-04-x64',
    ],
    'ssh' => [
        'key_path' => '~/.ssh/deploy_key.pub',
        'user' => 'forge',
    ],
    'domain' => [
        'name' => 'myapp.com',
        'subdomains' => ['api', 'www'],
    ],
    'ssl' => [
        'enabled' => true,
        'email' => 'admin@myapp.com',
        'type' => 'letsencrypt',
    ],
    'provision' => [
        'php' => '8.3',
        'nginx' => true,
        'database' => 'mysql',
        'system_packages' => ['git', 'curl', 'zip'],
    ],
    'deployment' => [
        'path' => '/var/www/myapp',
        'repository' => 'git@github.com:user/myapp.git',
        'branch' => 'main',
        'exclude' => ['.env', 'node_modules', 'storage/logs'],
    ],
];

Security Note

All sensitive configuration values (API tokens, passwords, SSH keys) are automatically masked in logs and UI responses. Use environment variables for production deployments.

Installation

# Install ForgeDeployment module
php forge.php package:install-module --module=forge-deployment

# Install with dependencies (ForgeHub, ForgeLogger, etc.)
php forge.php package:install-module forge-deployment forge-hub forge-logger

# Force reinstallation
php forge.php package:install-module --module=forge-deployment --force

Module Registration

ForgeDeployment automatically registers with Forge Kernel and provides:

  • Hub integration under /hub/deployment
  • Middleware and permission integration
  • Configuration defaults management
  • CLI command registration
  • Service container registration

Environment Setup

# Required environment variables
FORGE_DEPLOYMENT_DIGITALOCEAN_API_TOKEN=your_api_token
FORGE_DEPLOYMENT_CLOUDFLARE_API_TOKEN=your_cloudflare_token

# Optional configuration files
# .env.local - Local development overrides
# .env.production - Production-specific values

Usage Examples

Hub Dashboard Integration

ForgeDeployment provides a complete Hub dashboard for managing deployments: 

// Controller integration
#[Route("/hub/deployment")]
public function index(): Response
{
    $status = $this->deploymentHubService->getDeploymentStatus();
    $config = $this->deploymentHubService->getDeploymentConfig();
    $logs = $this->deploymentHubService->listDeploymentLogs();
    
    return $this->view("pages/hub/deployment", [
        'title' => "Deployment",
        'status' => $status,
        'config' => $config,
        'logs' => $logs,
    ]);
}

Custom Provider Development

Create custom cloud providers by implementing the ProviderInterface: 

class CustomProvider implements ProviderInterface
{
    public function createServer(ServerConfig $config): array
    {
        // Custom server creation logic
        return ['id' => 'server-123', 'ip' => '192.168.1.100'];
    }
    
    public function provisionSystem(ProvisionConfig $config): bool
    {
        // Custom provisioning logic
        return true;
    }
    
    public function configureDomain(string $domain): bool
    {
        // Custom domain configuration
        return true;
    }
}