Getting Started

Minimal Steps to First Deployment

Install the Bundle Add the bundle to your Symfony project via Composer:

composer require wunderfork/easy-deploy-bundle

Enable it in config/bundles.php:

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

Configure SSH Access Ensure SSH access is set up between your local machine and the remote server(s). Follow the SSH Configuration Tutorial for guidance.

Define Deployment Targets Create a deploy.php file in your project root (or configure via config/packages/easy_deploy.yaml). Example:

<?php
return [
    'deploy' => [
        'production' => [
            'host' => 'user@your-server.com',
            'path' => '/var/www/your-app',
            'repository' => 'git@github.com:your/repo.git',
            'branch' => 'main',
        ],
    ],
];

Run the Deployer Execute the deployment command:

php bin/console easy-deploy:deploy production

First Use Case: Zero-Downtime Deployment

Use the --no-downtime flag to ensure seamless deployments:

php bin/console easy-deploy:deploy production --no-downtime

Implementation Patterns

Core Workflows

Multi-Stage Deployments Define stages (e.g., staging, production) in deploy.php and deploy sequentially:

'deploy' => [
    'staging' => [...],
    'production' => [...],
];

Deploy to staging first, then promote to production:

php bin/console easy-deploy:deploy staging
php bin/console easy-deploy:deploy production

Custom Deployer Logic Extend the default deployer by creating a custom class (e.g., CustomDeployer) and configure it in deploy.php:
```
'deployer_class' => Wunderfork\EasyDeployBundle\Deployer\CustomDeployer::class,
```
Override methods like deploy() or postDeploy() in your custom class.
Git Integration Leverage Git hooks or post-deploy scripts for tasks like:
- Running migrations (php bin/console doctrine:migrations:migrate).
- Clearing caches (php bin/console cache:clear). Add these to the postDeploy hook in your custom deployer.
Environment-Specific Configs Use Symfony’s parameter bags or environment variables to manage stage-specific configs (e.g., .env.production):
```
'deploy' => [
    'production' => [
        'env_file' => '/var/www/your-app/.env.production',
    ],
];
```

Integration Tips

Symfony Flex Compatibility: Works seamlessly with Symfony 4/5 Flex projects. No extra configuration needed beyond the bundle enablement.
CI/CD Pipelines: Integrate with GitHub Actions, GitLab CI, or Jenkins by triggering the deploy command as a pipeline step. Example GitHub Actions workflow:
```
- name: Deploy to Production
  run: php bin/console easy-deploy:deploy production
```

Rollback Strategy: Use Git’s reset --hard in a custom deployer for rollbacks:

public function rollback()
{
    $this->run('cd {{ path }} && git reset --hard {{ previous_commit }}');
}

Gotchas and Tips

Pitfalls

SSH Key Management
- Issue: Failed SSH connections due to incorrect key permissions or missing keys.
- Fix: Ensure keys are added to ~/.ssh/authorized_keys on the remote server and have 600 permissions:
```
chmod 600 ~/.ssh/id_rsa
```
- Tip: Use ssh-add to cache keys temporarily:
```
ssh-add ~/.ssh/id_rsa
```
File Permissions
- Issue: Deployer fails to write files due to incorrect permissions on the remote server.
- Fix: Set up proper permissions for the deploy user (e.g., www-data):
```
sudo chown -R www-data:www-data /var/www/your-app
sudo chmod -R 755 /var/www/your-app
```
Git Repository Access
- Issue: Deployer cannot clone the repository due to SSH restrictions.
- Fix: Ensure the deploy user has SSH access to the Git server and the repository URL is correct (use SSH format: git@github.com:user/repo.git).
Downtime During Deployments
- Issue: Accidental downtime if --no-downtime is not used.
- Fix: Always use --no-downtime for production deployments or implement a custom swap mechanism (e.g., symlink-based deployments).
Outdated Documentation
- Issue: Some tutorials or examples may not align with the latest Symfony versions.
- Fix: Cross-reference with Symfony’s official docs and the bundle’s DefaultDeployer class for up-to-date patterns.

Debugging

Verbose Mode: Enable verbose output for troubleshooting:
```
php bin/console easy-deploy:deploy production -v
```

Dry Run: Test deployments without making changes:

php bin/console easy-deploy:deploy production --dry-run

Log Files: Check Symfony’s log directory (var/log) for detailed errors.

Extension Points

Custom Commands Extend the bundle by creating custom console commands. Example:

namespace App\Command;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Wunderfork\EasyDeployBundle\Deployer\DeployerInterface;

class CustomDeployCommand extends Command
{
    protected static $defaultName = 'app:custom-deploy';
    private $deployer;

    public function __construct(DeployerInterface $deployer)
    {
        $this->deployer = $deployer;
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $this->deployer->customLogic();
        return Command::SUCCESS;
    }
}

services:
    App\Command\CustomDeployCommand:
        arguments:
            $deployer: '@wunderfork_easy_deploy.deployer'
        tags: ['console.command']

Event Listeners Hook into the deploy lifecycle using Symfony events. Example:

namespace App\EventListener;
use Wunderfork\EasyDeployBundle\Event\DeployEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DeployListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            DeployEvent::PRE_DEPLOY => 'onPreDeploy',
            DeployEvent::POST_DEPLOY => 'onPostDeploy',
        ];
    }

    public function onPreDeploy(DeployEvent $event)
    {
        // Pre-deploy logic (e.g., backup database)
    }

    public function onPostDeploy(DeployEvent $event)
    {
        // Post-deploy logic (e.g., restart services)
    }
}

Configuration Overrides Override default configurations via config/packages/easy_deploy.yaml:

wunderfork_easy_deploy:
    deployer_class: App\Deployer\CustomDeployer
    default_options:
        keep_releases: 5
        no_downtime: true

Pro Tips

Backup Strategy: Implement a backup step in preDeploy() to snapshot the current release before deployment.

Environment Validation: Validate environment variables or configs post-deployment:

public function postDeploy()
{
    $this->run('php {{ path }}/bin/console debug:env APP_ENV');
}

Parallel Deployments: For multi-server setups, use SSH parallel execution tools like parallel-ssh (pssh) to speed up deployments.
Monitoring: Integrate with tools like New Relic or Datadog to monitor deployment health and performance.

Easy Deploy Bundle Wunderfork Laravel Package