Confusion when using a configuration file in a different directory

[joeshelton-wagento]

Deployer Version

v8.0.5

Target OS

MacOS 14.8.9

Which PHP version are you using?

PHP 8.5

Content of deploy.php or deploy.yaml

  # You can import other php or maml recipes.
  # Import recipes directly from recipe/ folder.
  import: [
    "recipe/magento2.php"
  ]

  config: {
    repository: "git@bitbucket.org:wagento-global/paas-poc.git"
    deploy_path: "~"
    current_path: "public_html"
    writable_mode: "chmod"
  }

  # Hosts
  hosts: {
    # Build artifact in pipeline
    "localhost": {
      local: true
    }
    # Deploy to proper host
    "production": {
      remote_user: "deployer"
      hostname: "fake.com"
      port: 29064
      branch: "main"
      "bin/php": "bin/cli deploy php"
      "bin/magento": "bin/cli deploy bin/magento"
    }
    # For testing locally
    "testbuild": {
        local: true
        build_from_repo: true
        artifact_dir: "testbuild"
        branch: "main"
    }
    "testdeploy": {
        local: true
        deploy_path: "testdeploy"
        "bin/php": "bin/cli deploy php"
        "bin/magento": "bin/cli deploy bin/magento"
    }
  }

  # Define tasks as list of steps to run,
  # or use array to strings to define group task.
  tasks: {
    # Manage Docker containers
    "docker:pull": [
      {
        run: "cd {{release_path}} && bin/cli docker pull"
      }
    ]
    "docker:up": [
      {
        run: "cd {{release_path}} && bin/cli docker up -d --remove-orphans"
      }
    ]
    "docker:down": [
      {
        run: "if [ -d {{previous_release}} ]; then cd {{previous_release}} && bin/cli docker down; fi"
      }
    ]
    # Disable / enable cron
    "cron:disable-and-wait": [
      {
        run: "if [ -d {{current_path}} ]; then {{bin/php}} {{current_path}}/bin/magento cron:remove || true; fi"
      }
      {
        run: "cd {{release_path}} && bash -c 'TIMEOUT=120; ELAPSED=0; while bin/cli docker exec -T fpm pgrep -f \"bin/magento +(cron:run)\" > /dev/null 2>&1; do if [ $ELAPSED -ge $TIMEOUT ]; then echo \"Timeout reached waiting for crons, proceeding...\"; break; fi; echo \"Waiting for active cron jobs to finish... ($ELAPSED/${TIMEOUT}s)\"; sleep 5; ELAPSED=$((ELAPSED+5)); done'"
      }
    ]
    "cron:enable": [
      {
        run: "cd {{release_path}} && {{bin/php}} {{bin/magento}} cron:install"
      }
    ]
  }

  # Hooks
  after: {
    # restart Docker with new definition
    # disable cron during deployment
    "magento:maintenance:enable-if-needed": [
      "cron:disable-and-wait"
      "docker:down"
      "docker:pull"
      "docker:up"
    ]
    "deploy:symlink": "cron:enable"
  }
}

Steps to reproduce

When running the following command...

dep -f .paas/deploy.maml artifact:deploy testdeploy -vvv

Deployer creates two deployment directories and does not use either one consistently. Note: the Magento 2 recipe is used. The intent is to test the deployment locally.

Output:

joeshelton@Joes-MBP paas-poc % dep -f .paas/deploy.maml artifact:deploy testdeploy -vvv
task deploy:info
[master] Starting server at http://127.0.0.1:61134
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61134 --task deploy:info --host testdeploy --file .paas/deploy.maml --decorated -vvv
[testdeploy] run if [ -d testdeploy/.dep ]; then echo +right; fi
[testdeploy] +right
[testdeploy] run cat .dep/latest_release || echo 0
[testdeploy] 1
[testdeploy] info deploying paas-poc to testdeploy (release 2)
done on testdeploy
[master] Stopping server at http://127.0.0.1:61134
done deploy:info 153ms
task deploy:setup
[master] Starting server at http://127.0.0.1:61139
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61139 --task deploy:setup --host testdeploy --file .paas/deploy.maml --decorated -vvv
[testdeploy] run [ -d testdeploy ] || mkdir -p testdeploy;
cd testdeploy;
[ -d .dep ] || mkdir .dep;
[ -d releases ] || mkdir releases;
[ -d shared ] || mkdir shared;
[testdeploy] run if [ ! -L public_html ] && [ -d public_html ]; then echo +true; fi
done on testdeploy
[master] Stopping server at http://127.0.0.1:61139
done deploy:setup 132ms
task deploy:lock
[master] Starting server at http://127.0.0.1:61144
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61144 --task deploy:lock --host testdeploy --file .paas/deploy.maml --decorated -vvv
[localhost] run git config --get user.name
[localhost] Joe Shelton
[testdeploy] run [ -f testdeploy/.dep/deploy.lock ] && echo +locked || echo $'Joe Shelton' > testdeploy/.dep/deploy.lock
done on testdeploy
[master] Stopping server at http://127.0.0.1:61144
done deploy:lock 134ms
task deploy:release
[master] Starting server at http://127.0.0.1:61149
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61149 --task deploy:release --host testdeploy --file .paas/deploy.maml --decorated -vvv
[testdeploy] run if [ -h release ]; then echo +true; fi
[testdeploy] run if [ -d releases ] && [ "$(ls -A releases)" ]; then echo +indeed; fi
[testdeploy] run if [ -d releases/2 ]; then echo +yes; fi
[testdeploy] run echo 2 > .dep/latest_release
[testdeploy] run echo $'{"created_at":"2026-10-13T20:09:23+0000","release_name":"2","user":"Joe Shelton","target":"HEAD"}' >> .dep/releases_log
[testdeploy] run mkdir -p releases/2
[testdeploy] run (man ln 2>&1 || ln -h 2>&1 || ln --help 2>&1) | grep -- --relative || true
[testdeploy] run ln -nfs releases/2 testdeploy/release
[testdeploy] ln: testdeploy/release: No such file or directory
[testdeploy] error in release.php on line 132:
[testdeploy] exit code 1 (General error)
[master] Stopping server at http://127.0.0.1:61149
done deploy:release 302ms
task deploy:failed
[master] Starting server at http://127.0.0.1:61154
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61154 --task deploy:failed --host testdeploy --file .paas/deploy.maml --decorated -vvv
done on testdeploy
[master] Stopping server at http://127.0.0.1:61154
done deploy:failed 121ms
task magento:config:import:on-current
[master] Starting server at http://127.0.0.1:61159
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61159 --task magento:config:import:on-current --host testdeploy --file .paas/deploy.maml --decorated -vvv
[testdeploy] run if [ -d public_html/. ] && [ -f public_html/./bin/magento ]; then echo +true; fi
[testdeploy] Current Magento installation is unavailable => import skipped
[testdeploy] App config import skipped
done on testdeploy
[master] Stopping server at http://127.0.0.1:61159
done magento:config:import:on-current 121ms
task magento:maintenance:disable
[master] Starting server at http://127.0.0.1:61164
[testdeploy] /opt/homebrew/Cellar/php/8.5.6/bin/php /Volumes/ProjectFiles/paas-poc/vendor/deployer/deployer/bin/dep worker --port 61164 --task magento:maintenance:disable --host testdeploy --file .paas/deploy.maml --decorated -vvv
[testdeploy] run if [ -d $(echo public_html) ]; then bin/cli deploy php public_html/./bin/magento maintenance:disable; fi
done on testdeploy
[master] Stopping server at http://127.0.0.1:61164
done magento:maintenance:disable 121ms
joeshelton@Joes-MBP paas-poc %

[TheMysteriousGhost]

The problem is the relative paths. deploy_path: "testdeploy" and current_path: "public_html" get resolved against whatever directory the command happens to be running in, and that changes during the deploy.

Most deploy tasks start with cd('{{deploy_path}}'). You can see it break in deploy:release: it has already cd'ed into testdeploy, and then runs

ln -nfs releases/2 {{deploy_path}}/release

testdeploy/release relative to testdeploy/ is testdeploy/testdeploy/release, which doesn't exist, hence ln: testdeploy/release: No such file or directory. Tasks that don't cd first resolve the same values from the project root instead, so one setting points at two different places depending on the task.

Use absolute paths and build current_path from deploy_path:

"testdeploy": {
    local: true
    deploy_path: "/Volumes/ProjectFiles/paas-poc/testdeploy"
    current_path: "{{deploy_path}}/public_html"
    "bin/php": "bin/cli deploy php"
    "bin/magento": "bin/cli deploy bin/magento"
}

For production, deploy_path: "~" is fine since ~ expands to an absolute path, but the global current_path: "public_html" has the same issue, so set it to "{{deploy_path}}/public_html" there too.

[joeshelton-wagento]

Thanks! An absolute path did indeed fix the issue. Behavior becomes the same regardless of where the configuration file is located.

I'll note that an absolute path does not meet my requirements. I'm attempting to create a configuration that would test the deployment locally across a team of people with different operating systems. Can't guarantee any absolute path would be present on multiple local systems. Only guarantee is what's checked out of the repository that the configuration file is in. But, I suppose compatibility with relative paths is a messy business :P

[tevinch]

An absolute path can be derived from each checkout, so teammates do not need the same host directory. Put this beside your existing .paas/deploy.maml as .paas/deploy.php:

<?php

namespace Deployer;

set('checkout_root', dirname(__DIR__));
import(__DIR__ . '/deploy.maml');

Then merge these fields into the existing local testdeploy host:

deploy_path: "{{checkout_root}}/testdeploy"
current_path: "{{deploy_path}}/public_html"

Keep its other fields, the Magento recipe import, and your existing tasks and hooks. From the checkout root, use -f .paas/deploy.php with your existing command; from elsewhere, pass the actual path to that PHP file. The anchor is evaluated from the checked-in file's location before MAML is imported; remote production hosts can keep their existing paths. See the import documentation.

Example and checks: the Magento recipe is used only for path inspection; a separate common-recipe fixture exercises inert artifact publication and checkout relocation.

The check passed with Deployer 8.0.5 and PHP 8.3.6 on Ubuntu 24.04: unchanged configuration survived physical relocation, and the common-recipe fixture published two artifacts while preserving the earlier release. This checks the local-path pattern, not your Magento application or Docker/cron hooks; macOS/PHP 8.5 and other operating systems were not tested.