Getting Started

Minimal Steps to First Deployment

Install the Bundle Add to composer.json:
```
{
    "require": {
        "easycorp/easy-deploy-bundle": "^1.0"
    }
}
```
Run composer require easycorp/easy-deploy-bundle.

Enable the Bundle Add to config/bundles.php:

return [
    // ...
    EasyCorp\Bundle\EasyDeployBundle\EasyDeployBundle::class => ['all' => true],
];

Configure SSH Access

Set up SSH keys for passwordless authentication between your local machine and the remote server.

Reference the remote server in config/packages/easy_deploy.yaml:

easy_deploy:
    servers:
        production:
            host: 'your-server.com'
            user: 'deploy-user'
            port: 22
            private_key: '%kernel.project_dir%/path/to/private_key'

First Deployment Run the default deployer command:
```
php bin/console easy-deploy:deploy production
```
This will clone the repo, pull updates, and deploy with zero downtime.

Where to Look First

Documentation: Start with Getting Started and Default Deployer.
Configuration: Review config/packages/easy_deploy.yaml for server and deployment settings.
Tutorials: Use Local SSH Config if SSH setup is tricky.

First Use Case: Deploying to a Single Server

Configure the server in easy_deploy.yaml.

Run the deploy command:

php bin/console easy-deploy:deploy production

Verify the deployment by checking the remote server’s application directory.

Implementation Patterns

Core Workflow: Multi-Stage Deployments

Define Stages Configure multiple environments (e.g., staging, production) in easy_deploy.yaml:

easy_deploy:
    servers:
        staging:
            host: 'staging.example.com'
            user: 'deploy'
        production:
            host: 'prod.example.com'
            user: 'deploy'

Deploy to a Specific Stage

php bin/console easy-deploy:deploy staging

Sequential Deployments Use a script or CI/CD pipeline to deploy to staging first, then promote to production:

php bin/console easy-deploy:deploy staging
# Test staging, then:
php bin/console easy-deploy:deploy production

Integration with Symfony Workflows

Pre/Post Deployment Hooks Extend the deployer to run custom commands before/after deployment:

// src/EasyDeploy/CustomDeployer.php
namespace App\EasyDeploy;

use EasyCorp\Bundle\EasyDeployBundle\Deployer\DeployerInterface;

class CustomDeployer implements DeployerInterface
{
    public function deploy()
    {
        // Pre-deployment: e.g., database migrations
        $this->run('php bin/console doctrine:migrations:migrate --no-interaction');

        // Call parent deploy logic
        parent::deploy();

        // Post-deployment: e.g., cache warmup
        $this->run('php bin/console cache:clear');
    }
}

easy_deploy:
    deployer: App\EasyDeploy\CustomDeployer

Environment-Specific Configurations Use Symfony’s environment variables or parameter bags to customize deployments per stage:

# config/packages/easy_deploy_production.yaml
easy_deploy:
    servers:
        production:
            # Override settings for production
            deploy_path: '/var/www/production'
            keep_releases: 5

Advanced Patterns

Multi-Server Deployments Deploy to multiple servers simultaneously by defining an array of servers:

easy_deploy:
    servers:
        load_balancers:
            - host: 'lb1.example.com'
              user: 'deploy'
            - host: 'lb2.example.com'
              user: 'deploy'

Deploy to all load balancers:

php bin/console easy-deploy:deploy load_balancers

Git Strategies Customize Git operations (e.g., shallow clones, specific branches) in the deployer:

protected function cloneRepository()
{
    $this->run('git clone --depth 1 --branch master git@github.com:user/repo.git ' . $this->getDeployPath());
}

Rollback Mechanism Leverage EasyDeploy’s release management to roll back:

php bin/console easy-deploy:rollback production 2023-01-01T12:00:00+00:00

Gotchas and Tips

Pitfalls and Debugging

SSH Connection Issues
- Symptom: Deployment fails with "Permission denied (publickey)".
- Fix: Ensure SSH keys are properly set up and referenced in easy_deploy.yaml. Use the Troubleshooting Guide.
- Tip: Test SSH access manually:
```
ssh -i %kernel.project_dir%/path/to/private_key deploy@your-server.com
```
File Permissions
- Symptom: Deployed files have incorrect permissions (e.g., 644 instead of 755).
- Fix: Customize the chmod command in your deployer or use umask:
```
easy_deploy:
    servers:
        production:
            deploy_path: '/var/www/prod'
            chmod: '755'
```
Zero Downtime Deployments
- Symptom: Application crashes during deployment.
- Fix: Ensure your web server (e.g., Nginx/Apache) is configured to use the current symlink. EasyDeploy handles this by default, but verify:
```
easy_deploy:
    servers:
        production:
            symlink: 'current'
```

Large Repositories

Symptom: Slow deployments due to large Git history.

Fix: Use shallow clones or sparse checkouts:

protected function cloneRepository()
{
    $this->run('git clone --depth 1 git@github.com:user/repo.git ' . $this->getDeployPath());
}

Configuration Quirks

Private Key Paths
- Use absolute paths for private_key in easy_deploy.yaml to avoid issues with Symfony’s kernel project directory resolution:
```
easy_deploy:
    servers:
        production:
            private_key: '/home/user/.ssh/id_rsa'
```
Overriding Defaults
- Default deployer settings (e.g., keep_releases, deploy_path) can be overridden globally or per server. Global overrides in easy_deploy.yaml take precedence over defaults:
```
easy_deploy:
    keep_releases: 3  # Overrides default (5)
    deploy_path: '/var/www/shared'  # Overrides per-server deploy_path if not specified
```

Environment Variables

Use Symfony’s parameter bag or %env() for sensitive data (e.g., SSH keys):

easy_deploy:
    servers:
        production:
            private_key: '%env(SSH_PRIVATE_KEY_PATH)%'

Extension Points

Custom Deployer Classes Extend EasyCorp\Bundle\EasyDeployBundle\Deployer\AbstractDeployer to add custom logic:

namespace App\EasyDeploy;

use EasyCorp\Bundle\EasyDeployBundle\Deployer\AbstractDeployer;

class CustomDeployer extends AbstractDeployer
{
    protected function getDeployPath()
    {
        return $this->getServer()->getDeployPath() . '/app';
    }

    protected function postDeploy()
    {
        $this->run('php bin/console cache:warmup');
    }
}

easy_deploy:
    deployer: App\EasyDeploy\CustomDeployer

Event Listeners Use Symfony events to hook into the deployment lifecycle (e.g., trigger notifications):

// src/EventListener/DeployListener.php
namespace App\EventListener;

use EasyCorp\Bundle\EasyDeployBundle\Event\DeployEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DeployListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            DeployEvent

Easy Deploy Bundle Laravel Package