DOCSEARCHbyAlgolia
Submit Docs

Deployer Documentation

website·Indexed 36 days ago

https://deployer.org/

Documentation for Deployer, a PHP deployment tool. Includes API references for host management and task execution, CLI usage, and deployment recipes for frameworks and CMSs such as Laravel, Symfony, WordPress, Magento 2, and Yii. Covers versions 7.x and 8.x, including upgrade guides and configuration for various contrib plugins.

Tokens
98.5K
Snippets
726
Records
1K
Agent score
71%

What's inside Deployer

  1. Overview of ElephpantDB SQL database

    ElephpantDB is a small, experimental SQL database engine written entirely in PHP and shipped as a single file. It uses an append-only heap for row storage where records are identified by byte offsets. Updates create new row versions, and deletes mark records as dead, with a VACUUM command used for cleanup. It includes features such as file locking, checksums, crash recovery, and hash indexes (which act as rebuildable caches).

  2. Overview of MAML syntax for Deployer recipes

    MAML is a JSON superset used for Deployer recipes (files with the .maml extension). It supports comments, raw multiline strings, optional commas, unquoted keys, and ordered objects.

    Key syntax rules:

    • Comments: Use # for end-of-line comments.
    • Strings: Standard double-quoted strings ("...") with escapes, or raw strings ("""...""") where newlines are preserved and escapes are ignored (ideal for scripts).
    • Numbers/Booleans: Supports integers, floats, true, false, and null.
    • Arrays/Objects: Comma- or newline-separated. Keys can be unquoted identifiers or quoted strings. Keys containing dots or colons must be quoted.

  3. Understand the Symfony deployment workflow

    The deploy task for Symfony follows a specific sequence of operations to ensure a zero-downtime release:

    1. deploy:prepare: Prepares the new release (includes setup, lock, update_code, env, shared, and writable).
    2. deploy:vendors: Installs Composer dependencies.
    3. deploy:cache:clear: Clears the Symfony cache.
    4. deploy:publish: Publishes the release (includes symlinking the current folder, unlocking, cleanup, and success notification).

  4. Display deployment information using deploy:info

    The deploy:info task displays summary information about the current deployment, utilizing the what and where configuration settings to identify the project and target environment.

  5. Understand the Laravel deployment workflow

    The deploy task for Laravel executes the following sequence of operations:

    1. deploy:prepare: Prepares the release (includes info, setup, lock, release, update_code, env, shared, and writable).
    2. deploy:vendors: Installs Composer dependencies.
    3. artisan:storage:link: Creates symbolic links for the application storage.
    4. artisan:config:cache: Caches configuration for faster loading.
    5. artisan:route:cache: Caches routes for faster registration.
    6. artisan:view:cache: Compiles Blade templates.
    7. artisan:event:cache: Caches events and listeners.
    8. artisan:migrate: Runs database migrations.
    9. deploy:publish: Publishes the release (includes symlink, unlock, cleanup, and success).

  6. Deployer 8.x New Features Overview

    Deployer 8.x introduces several new capabilities:

    • MAML recipes: Support for deploy.maml recipe format.
    • local_archive strategy: A new update_code_strategy that copies code from the local machine instead of a remote repository.
    • Host::setShellPath(): Ability to customize the shell path on a per-host basis.
    • CI User Detection: Automatic detection of usernames from GitHub Actions, GitLab, CircleCI, and Drone CI.
    • ACL Improvements: New writable_acl_groups and writable_acl_force options for deploy:writable.

  7. Use MAML recipes in Deployer v8

    Deployer v8 introduces MAML (a JSON-based language) as a replacement for YAML recipes. MAML provides better error reporting with accurate line numbers and syntax highlighting. MAML recipes are fully interoperable with PHP recipes.
    {
  import: ["recipe/common.php"]

  hosts: {
    "deployer.org": {
      remote_user: "deployer"
      deploy_path: "~/deployer.org"
    }
  }

  tasks: {
    deploy: [
      "deploy:prepare"
      "deploy:publish"
    ]

    build: [
      { runLocally: "npm run clear" }
      { runLocally: "npm run build" }
    ]

    "deploy:update_code": [
      {
        upload: {
          src: "build/"
          dest: "{{release_path}}"
        }
      }
    ]
  }
}

  8. Integrate Supervisord Monitor into Deployer

    The supervisord-monitor recipe allows you to manage Supervisord processes (restart, start, stop) via the Supervisord server monitoring web tool using cURL. This is particularly useful when the deployment user lacks sufficient CLI permissions to restart daemon processes directly.
    require 'contrib/supervisord-monitor.php';

  9. Integrate cPanel API recipe into Deployer

    The cPanel recipe allows you to automate the creation and deletion of addon domains and databases via the cPanel 2 API. This is particularly useful for staging environments where each branch requires its own subdomain and database.
    require 'contrib/cpanel.php';

  10. Understand the CodeIgniter 4 deployment workflow

    The deploy task for CodeIgniter 4 follows a specific sequence of steps to ensure a safe release:

    1. Preparation: deploy:prepare (includes setup, lock, release, update_code, env configuration, shared symlinks, and setting writable directories).
    2. Dependencies: deploy:vendors installs PHP dependencies.
    3. Optimization: spark:optimize prepares the app for production.
    4. Database: spark:migrate runs pending database migrations.
    5. Publishing: deploy:publish (includes symlinking the release, unlocking, and cleaning up old releases).

  11. Understand the Contao deployment workflow

    The deploy task for Contao is a group task that executes the following sequence to ensure zero-downtime deployment:

    1. deploy:prepare: Prepares the new release (includes setup, lock, release, update_code, env, shared, and writable).
    2. deploy:vendors: Installs PHP dependencies.
    3. contao:maintenance:enable: Puts the site into maintenance mode.
    4. contao:migrate: Runs database migrations.
    5. contao:maintenance:disable: Takes the site out of maintenance mode.
    6. deploy:publish: Publishes the release (includes symlinking, unlocking, cleanup, and success notification).

  12. Understand Deployer's master-worker subprocess architecture

    Deployer achieves parallelism by spawning one subprocess (worker) per host rather than using threading or async frameworks. This avoids PHP's concurrency limitations while allowing shell commands to run in parallel. A 'master' process coordinates these workers, managing the global configuration and handling user interaction.