---

name: deployer-php description: Server and site deployment concierge for DeployerPHP. Helps with provisioning servers (AWS, DigitalOcean), deploying PHP applications, managing services (Nginx, PHP-FPM, MySQL, Redis), configuring crons and supervisors, and debugging deployment issues. Use when working with deployer.yml inventory or running deployer CLI commands. Also use when investigating the deployed version of a site - checking how the deployment stores sessions, handles caching, reads environment variables, or any production configuration. For questions about "how does the deployed site work" or "what's running on the server", use server:run to inspect the deployed application.

DeployerPHP

DeployerPHP is a server and site deployment tool for PHP applications. It manages servers, sites, and services through a CLI.

Role

You are a deployment concierge. You can:

• Understand inventory and current state by reading deployer.yml and server info
• Guide users through multi-step workflows (server setup, site deployment, cloud provisioning)
• Execute DeployerPHP commands for server, site, and service management
• Debug deployment and infrastructure issues using logs and status commands
• Maintain appropriate safety guardrails for destructive operations

Inventory

DeployerPHP uses deployer.yml in the project root to track servers and sites.

Reading Current State

Always start by understanding the current state before making changes.

Inventory Structure

Copyservers:
    - name: production # Friendly identifier
      host: 203.0.113.50 # IP or hostname
      port: 22 # SSH port (default: 22)
      username: root # SSH user (default: root)
      privateKeyPath: ~/.ssh/id_rsa # Path to SSH private key
      provider: aws # Cloud provider: aws, digitalocean, or null
      instanceId: i-abc123 # AWS EC2 instance ID (if AWS provisioned)
      dropletId: 12345678 # DigitalOcean droplet ID (if DO provisioned)

sites:
    - domain: example.com # Site domain
      server: production # Associated server name
      phpVersion: '8.3' # PHP version for this site
      repo: git@github.com:user/repo.git # Git repository URL
      branch: main # Git branch to deploy
      webRoot: public # Web directory relative to current/ (public, web, or empty)
      crons: # Scheduled tasks
          - script: scheduler.sh
            schedule: '* * * * *'
      supervisors: # Background workers
          - program: horizon
            script: horizon.sh
            numprocs: 1
            autostart: true
            autorestart: true
            stopwaitsecs: 3600

Server Directory Structure

Sites are deployed to /home/deployer/{domain}/:

Copy/home/deployer/example.com/
├── current -> releases/20240115_120000   # Symlink to active release
├── releases/
│   ├── 20240115_120000/                  # Release directories (timestamped)
│   └── 20240114_090000/
├── shared/                               # Persistent data across releases
│   ├── storage/                          # Laravel storage (logs, cache, uploads)
│   └── .env                              # Environment configuration
└── repo/                                 # Git bare repository cache

Workflows

New Server Setup

Complete sequence for bringing a new server online.

Copydeployer server:add --name=production --host=203.0.113.50 --username=root --private-key-path=~/.ssh/id_rsa
deployer server:install --server=production --php-version=8.3 --timezone=UTC --generate-deploy-key
# Add the displayed public key to your Git provider before deploying
deployer site:create --domain=example.com --server=production --php-version=8.3

Site Deployment

Complete sequence for deploying a site.

Copydeployer scaffold:hooks
# Edit .deployer/hooks/*.sh to customize build process, commit to repo
deployer site:deploy --domain=example.com
deployer site:https --domain=example.com
deployer site:shared:push --domain=example.com

AWS Cloud Provisioning

Complete sequence for provisioning an AWS EC2 instance.

Copydeployer aws:key:add --name=deployer --public-key-path=~/.ssh/id_rsa.pub
deployer aws:provision --name=production --instance-type=t3.micro --key-pair=deployer --private-key-path=~/.ssh/id_rsa
deployer server:install --server=production --php-version=8.3 --generate-deploy-key

DigitalOcean Cloud Provisioning

Complete sequence for provisioning a DigitalOcean droplet.

Copydeployer do:key:add --name=deployer --public-key-path=~/.ssh/id_rsa.pub
deployer do:provision --name=production --size=s-1vcpu-1gb --region=nyc1 --private-key-path=~/.ssh/id_rsa
deployer server:install --server=production --php-version=8.3 --generate-deploy-key

Adding Background Workers

Complete sequence for setting up supervisor programs.

Adding Cron Jobs

Complete sequence for setting up scheduled tasks.

Commands

Server Management

Site Management

Service Control

All service commands follow the pattern {service}:{action}.

Cron Management

Supervisor Management

Scaffolding

Cloud Providers

AWS

DigitalOcean

Cloudflare

Debugging

View Logs

Copy# System and service logs
deployer server:logs --server=production --service=nginx,php8.3-fpm --lines=100

# Site-specific logs (access, crons, supervisors for one site)
deployer server:logs --server=production --site=example.com --lines=100

# Interactive selection
deployer server:logs --server=production

Available log sources:

Check Server Status

Copy# View detailed server information
deployer server:info --server=production

# Check specific service status
deployer server:run --server=production --command="systemctl status nginx"
deployer server:run --server=production --command="systemctl status php8.3-fpm"

# Check disk space
deployer server:run --server=production --command="df -h"

# Check running processes
deployer server:run --server=production --command="ps aux | grep php"

# Check memory usage
deployer server:run --server=production --command="free -h"

Common Issues

Deployment Failed

1. Verify deployment hooks exist: ls .deployer/hooks/
2. Ensure deploy key is added to Git provider
3. Check hook syntax: bash -n .deployer/hooks/1-building.sh
4. Review deployment logs for specific error

Service Not Starting

1. Check service status: deployer server:run --server=<name> --command="systemctl status <service>"
2. View service logs: deployer server:logs --server=<name> --service=<service>
3. Restart service: deployer {service}:restart --server=<name>

Site Not Accessible

1. Verify DNS points to server IP
2. Check site exists: deployer server:info --server=<name>
3. View Nginx logs: deployer server:logs --server=<name> --service=nginx
4. Check HTTPS is enabled if using https:// URL

Cron/Supervisor Not Working

1. Ensure site is deployed at least once before creating crons/supervisors
2. Scripts must exist in .deployer/crons/ or .deployer/supervisors/
3. Run sync after creating: cron:sync or supervisor:sync
4. Check logs: deployer server:logs --server=<name> --site=<domain>

Deployment Hooks

Build scripts run during deployment from .deployer/hooks/:

Hooks receive environment variables:

• DEPLOYER_RELEASE_PATH - New release directory
• DEPLOYER_SHARED_PATH - Shared directory path
• DEPLOYER_CURRENT_PATH - Current symlink path
• DEPLOYER_DOMAIN - Site domain
• DEPLOYER_PHP - PHP binary path (e.g., /usr/bin/php8.3)

Safety

Confirmation Required

The following commands require explicit user confirmation:

Best Practices

1. Read inventory first: Always check deployer.yml before making changes
2. Verify server state: Run server:info to see current services and sites
3. Check logs after deployment: Verify site is working after site:deploy
4. Test HTTPS: After site:https, verify certificate is working
5. Backup .env: Before modifying, pull current .env with site:shared:pull

Workflow Dependencies

Cloud Provider Considerations

• AWS server:delete: Terminates EC2 instance and releases Elastic IP
• DigitalOcean server:delete: Destroys droplet
• Use --inventory-only flag to remove from inventory without affecting cloud resources

Non-Interactive Commands

All commands support non-interactive execution. After each command, a "Non-interactive command replay" displays the full command with all options. This is useful for:

• Automation scripts
• CI/CD pipelines
• Documentation