1 · Deployer (zero-downtime)

TL;DR

Objective — install Deployer and author deploy.php for atomic, zero-downtime releases (symlinked current → timestamped releases, shared storage + .env, retention, hooks, confirmed server binaries) so a failed deploy never takes the site down and rollback is a symlink flip.

Steps at a glance:

1. Install the Deployer CLI — Get dep on the PATH so every later task can run.
2. Learn the configuration API before touching deploy.php — Deployer’s DSL has four functions that look interchangeable but behave very differently. Picking the wrong one silently overrides recipe defaults — the exact bug class behind a real 90-minute production debug session (see the .env warning below).
3. Create and configure deploy.php — On a first run, copy the template; on a rerun, never blindly cp over an existing deploy.php — it holds your real hostnames, SSH ports, users, and binary paths.
4. Confirm the server binary paths — Shared hosting often exposes the wrong /usr/bin/php. Confirm the domain’s deploy PHP and pin Deployer’s PHP binary to it; Phase 5 writes the Composer platform pin immediately before the first live deploy.
5. Disable migrations for the first deploy — Running migrations before the vendor installer wizard causes schema conflicts. Comment the hook out for deploy #1, then re-enable after the installer runs in Phase 5.
6. Validate, then verify SSH access — Prove the file parses and the servers are reachable before any real deploy.

User part + done-when

👤 User part — almost none on your machine: an agent can install the CLI, author deploy.php, and run the dry run. A person is only needed if a server lacks the SSH alias or the server can’t reach GitHub — adding a deploy key in the repo’s browser settings is a dashboard action.

Done when dep --version returns Deployer 7.x, php -l deploy.php is clean, dep list shows 20+ tasks, the configured hosts answer over SSH, and dep deploy "$DEPLOY_TARGET" --plan reaches the symlink step for the selected non-production target from Zaj-PROJECT.md.  ·  ⏱ ~30–45 min  ·  🔀 mostly agent-runnable (👤 only for a deploy-key add).

Background

Deployer gives you atomic, zero-downtime releases: each deploy builds a fresh timestamped directory, links shared state into it, runs your hooks, and only on success flips a current symlink. A failed deploy never takes the site down, and rollback is a symlink flip back to the previous release.

Stop if shared-hosting readiness is not clean

Do not start this page until Phase 3 Step 7 · Shared-hosting readiness is checked off. Deployer assumes the hosting account’s ~/Admin-Server/ toolkit is alive: status.sh exits 0, cron-backed logs are fresh, monitored-paths.conf includes ~/.ssh/authorized_keys plus this app’s domain path, and deploy notifications are either configured in server.env or explicitly accepted as no-op.

SSH alias discovery before declaring a blocker

Before reporting “SSH credentials missing,” check the operator’s machine config. A previous project may already have a working alias for this server:

grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_ALIAS="<selected-environment-ssh-alias>"
PHPBIN="<versioned-php-path-if-known-or-php>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; reuse the alias if host/user/port match the target server

Record the non-secret alias/host/user/port in Zaj-PROJECT.md. If an alias exists but points at an old IP, update that stanza instead of creating a duplicate. If no alias exists, create one using Phase 2’s SSH procedure.

Deploy target names come from Zaj-PROJECT.md

The examples use Deployer target staging because it is common, not because it is required. Read the Deploy target column in Zaj-PROJECT.md and set DEPLOY_TARGET to the selected non-production row (staging, qa, uat, client-demo, etc.). Production remains its own target and is exercised later.

flowchart TD
  D["dep deploy <target>"] --> R["releases/2026-06-09-1/"]
  R --> SH["link shared: storage/, .env"]
  SH --> H["hooks: migrate · cache warm · queue restart"]
  H --> SY["flip current → new release"]
  SY --> OK["live ✅ (old release kept for rollback)"]
  style SY fill:#0b3,stroke:#062,color:#fff

Steps

1. Install the Deployer CLI

Get dep on the PATH so every later task can run.

1. Check for, then install, Deployer.

   dep --version                          # already installed?
   composer global require deployer/deployer
   dep --version | grep -E 'Deployer +7\.'
   # Expected: "Deployer 7.x.x" after install or from the existing dep binary

   • ✅ dep is installed and reports Deployer 7.x. If it reports Deployer 6 or 8+, use the matching docs before continuing.

2. Add the Composer global bin to PATH if dep is still not found.

   COMPOSER_BIN="$(composer global config bin-dir --absolute)"
   grep -q "$COMPOSER_BIN" ~/.zshrc \
     || echo "export PATH=\"\$PATH:$COMPOSER_BIN\"" >> ~/.zshrc
   source ~/.zshrc
   dep --version
   # Expected: dep --version returns "Deployer 7.x.x"

   • ✅ dep --version returns Deployer 7.x.x.

IDE warnings in deploy.php are not the gate

If Deployer is installed as a global Composer package or PHAR, VS Code / Cursor may mark the Deployer globals (set(), host(), add(), after()) as undefined and show hundreds of Problems. That is expected editor noise, not deploy proof. The real gates are php -l deploy.php and dep list.

To make the editor resolve Deployer symbols, prefer adding Deployer as a project-local dev dependency when the project can carry dev packages:

composer require --dev deployer/deployer
vendor/bin/dep list
# Expected: project-local dep parses deploy.php; IDE symbol resolution usually clears after reload

2. Learn the configuration API before touching deploy.php

Deployer’s DSL has four functions that look interchangeable but behave very differently. Picking the wrong one silently overrides recipe defaults — the exact bug class behind a real 90-minute production debug session (see the .env warning below).

Function	Semantics	Use when
set('key', $v)	Replaces the value, overriding recipe defaults	Defining a value from scratch, or intentionally overriding a default
add('key', $v)	Merges into an existing array, preserving defaults	Extending a recipe-default list with your own entries
get('key')	Reads the current value	Referencing a value inside a task closure
has('key')	Checks whether a value is defined	Conditional logic on a setting

Rule of thumb

If the recipe provides an array default you want to keep, use add(). If it’s a scalar (like keep_releases) or you mean to fully replace an array, use set(). When in doubt, add() is safer — the worst case is a redundant entry; the worst case of set() is silently dropping a critical default.

Laravel recipe array defaults you can silently destroy with set():

Setting	Recipe default	If you set() it wrong
shared_files	['.env']	Drops .env from the symlink list — every release boots on .env.example values.
shared_dirs	['storage']	Logs, uploads, and framework cache get wiped on every deploy.
writable_dirs	['bootstrap/cache', 'storage', 'storage/app', 'storage/app/public', 'storage/framework', 'storage/framework/cache', 'storage/framework/sessions', 'storage/framework/views', 'storage/logs']	A shorter replacement list means Laravel cannot write missing paths at runtime → 500s after deploy.
clear_paths	[]	Safe to set() or add(); use add() for symmetry with the GIT_ONLY_PATHS check on the CI page.
keep_releases	10	Safe to set() — scalar, not array.
bin/php	Auto-detected	Safe to set() — you usually want to override detection on shared hosting.

Quick audit: grep -nE "^\\s*set\\('(shared_files|shared_dirs|writable_dirs|clear_paths)'" deploy.php — any hit on an array key means you must confirm the replacement includes every recipe-default entry, or switch to add().

3. Create and configure deploy.php

On a first run, copy the template; on a rerun, never blindly cp over an existing deploy.php — it holds your real hostnames, SSH ports, users, and binary paths. Reconcile instead.

1. Detect first-run vs rerun before copying anything.

   [ -f deploy.php ] && echo "RERUN — reconcile, do not overwrite" || echo "FIRST RUN — cp template"
   # Expected: "FIRST RUN" on a fresh project, "RERUN" if deploy.php already exists

   • ✅ You know whether to copy the template or reconcile an existing file.

2. Define the core settings. At minimum:

   • shared_dirs → storage (persist uploads/logs/sessions across releases)

   • shared_files → .env (the production env lives server-side, shared)

   • keep_releases → e.g. 5 (retention for fast rollback)

   • hooks → after('deploy:vendors', 'artisan:migrate') for migrations; after('deploy:symlink', 'artisan:storage:link') so each fresh release re-creates public/storage → shared storage/app/public; and any cache-warm / queue-restart hooks that should run after the current symlink flips

   • ✅ shared_dirs, shared_files, keep_releases, the storage-link hook, and the migrate/cache hooks are all defined.

3. Map the template branch names to this project’s branch model. Templates often use staging and production branch names, while setup-new projects commonly use develop as the default work branch and main as the protected release/tag branch. Read Zaj-PROJECT.md, then set each Deployer host’s branch/source explicitly instead of inferring it from the target name.

   host('staging')
       ->set('branch', 'develop'); // selected non-production source branch from Zaj-PROJECT.md
   
   host('production')
       ->set('branch', 'main'); // release/tag branch, not the default PR target

   • ✅ Deployer target names (staging, qa, production) are mapped to the actual Git branches recorded in Zaj-PROJECT.md.

4. Write shared_dirs / shared_files correctly — two silent footguns.

   set('shared_dirs', [
       'storage',        // all of storage — DO NOT list subdirs like storage/app
   ]);
   
   // ✅ add() MERGES with the recipe default ['.env'] — .env stays shared
   add('shared_files', [
       // '.env' is already in the recipe default — do NOT repeat it
       // add only files OUTSIDE any shared_dirs directory
   ]);

   • ✅ storage is the only shared dir (no nested subdirs); .env is shared via add(), not set().

5. Register extra migration paths — module-based CodeCanyon apps ship migrations outside database/migrations/, and the recipe won’t run them unless you list each path.

   find packages -type d -name "Migrations" 2>/dev/null
   # Expected: one path per module that ships its own migrations

   set('extra_migration_paths', [
       'packages/<vendor>/*/src/Database/Migrations',
       'packages/<modules-namespace>/*/src/Database/Migrations',
       'database/migrations-<suffix>',
   ]);
   set('has_migration_installer_check', true);

   • ✅ Every Migrations directory found by find packages is covered by a pattern in extra_migration_paths.

Audit clear_paths — dev configs ship to prod without it

clear_paths deletes files from each release that must never reach the server. git clone on the server pulls in everything committed, so any committed-but-dev-only file lands in production unless clear_paths removes it.

Path	Why it must be cleared
boost.json	Laravel Boost config — committed, not gitignored. Contains MCP server config + project Boost settings.
.mcp.json	Editor/agent MCP server registration — exposes MCP server list and any embedded local-MCP credentials.
.claude/ .cursor/ .windsurf/	AI rules/configs — dev-only.
Tools/	Agent/build helper scripts, including prompt capture and audit tools — project-local, not web runtime.
Admin-Local/ _Source/ node_modules/ tests/ .github/	Build/dev/source dirs. Some are normally gitignored; this is defense in depth.
CLAUDE.md AGENTS.md README.md Zaj-PROJECT.md Zaj-PROGRESS.md Zaj-BACKLOG.md Zaj-CHANGELOG.md Zaj-CUSTOMIZATIONS.md CHANGELOG.md .editorconfig phpunit.xml atlas.hcl	Docs/config that should not be on a production server. Zaj-* files are ours; an unprefixed vendor CHANGELOG.md, if present, is vendor/framework-owned and still dev-only.

add('clear_paths', [
    'boost.json', '.mcp.json',
    '.claude', '.cursor', '.windsurf', '.agent',
    'Tools', 'Admin-Local', '_Source', 'tests', '.github',
    'CLAUDE.md', 'AGENTS.md', 'README.md',
    'Zaj-PROJECT.md', 'Zaj-PROGRESS.md', 'Zaj-BACKLOG.md', 'Zaj-CHANGELOG.md', 'Zaj-CUSTOMIZATIONS.md',
    'CHANGELOG.md', 'atlas.hcl',
]);

for f in boost.json .mcp.json CLAUDE.md AGENTS.md Zaj-PROJECT.md Zaj-PROGRESS.md Zaj-BACKLOG.md Zaj-CHANGELOG.md Zaj-CUSTOMIZATIONS.md atlas.hcl; do
  [ -f "$f" ] && { grep -q "'$f'" deploy.php && echo "✅ $f cleared" || echo "❌ $f committed but NOT in clear_paths — add it"; }
done
[ -d Tools ] && { grep -q "'Tools'" deploy.php && echo "✅ Tools cleared" || echo "❌ Tools committed but NOT in clear_paths — add it"; }

Symmetry rule: every path you add to clear_paths must also appear in GIT_ONLY_PATHS on the CI + ServerSync page, or the next ServerSync run proposes deleting those files from Git.

Never set('shared_files', [])

The Laravel recipe default for shared_files is ['.env']. Using set() replaces that default and drops .env from the symlink list — so every release boots with .env.example values instead of your real env. In one real incident this surfaced as a Connection refused 127.0.0.1:6379 during cache clear and burned 90 minutes pointed at the wrong subsystem. Always add(); never set() an empty/partial list.

Don’t nest shared dirs — 'storage' already includes storage/app, storage/logs, etc. Listing a subdir alongside it breaks symlink creation.

Each release needs public/storage re-linked — the recipe won’t do it

storage/ is shared across releases, but every deploy builds a fresh release directory whose public/storage symlink does not exist until something creates it. The Laravel Deployer recipe does not run php artisan storage:link for you, so without a hook every /storage/* URL (user uploads, public media) returns 403/404 on the new release. Wire it after the symlink flips:

after('deploy:symlink', 'artisan:storage:link');

# After a deploy, confirm the live release's public/storage link resolves (not a stale /var/www path)
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md
dep run 'cd current && readlink public/storage' --selector "alias=$DEPLOY_TARGET"
# Expected: public/storage → ../storage/app/public, NOT an absolute /var/www/... target

In-tree module apps (e.g. CodeCanyon vendors that ship assets under packages/<vendor>/<module>/src/... referenced as /packages/... URLs) also need public/packages re-linked per release, or module images 404. Add a matching task and after('deploy:symlink', …) hook that runs ln -sfn ../packages public/packages in the release root. Restrict /packages to asset extensions at the web server so raw .php source under it is never served.

4. Confirm the server binary paths

Shared hosting often exposes the wrong /usr/bin/php. Confirm the correct PHP per host so Deployer uses the versioned CLI binary your selected environment row records. This is an [AUTHOR] step: Phase 4 records the deploy PHP facts and proves the dry-run graph; Phase 5 writes the Composer platform pin immediately before the first live deploy.

1. Discover the available PHP binaries on the server.

   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md
   dep run 'ls /usr/bin/php* /opt/alt/php*/usr/bin/php 2>/dev/null | sort' --selector "alias=$DEPLOY_TARGET"
   # Expected: absolute paths to the PHP binaries present on the host

   • ✅ You have candidate versioned PHP binaries. Do not rely on login-shell Composer; Deployer’s vendors task will verify the configured Composer install path under the selected PHP.

2. Confirm both server PHP surfaces. On shared hosting, web PHP and CLI PHP are separate. The hosting panel controls the domain’s web PHP; Deployer runs the versioned CLI binary.

   BIN_PHP="/opt/alt/php83/usr/bin/php"   # example: versioned binary, not login-shell php
   dep run "$BIN_PHP -v | head -1" --selector "alias=$DEPLOY_TARGET"
   dep run "php -v | head -1" --selector "alias=$DEPLOY_TARGET"     # diagnostic only — login-shell PHP may differ
   # Expected: BIN_PHP is the confirmed deploy PHP. Bare php may differ and is not the deploy proof.

   • ✅ Zaj-PROJECT.md records the domain web PHP and the versioned CLI BIN_PHP path for the selected non-production and production rows.

3. Pin bin/php to the domain’s deploy PHP path.

   set('bin/php', '/opt/alt/php83/usr/bin/php'); // match the confirmed deploy PHP binary

   • ✅ bin/php points at the confirmed versioned deploy PHP binary.

4. Record the Phase 5 platform-pin carry-forward. Do not write Composer’s platform setting in Phase 4. Store the confirmed deploy PHP version, the web-PHP selector value, and the versioned CLI binary in Zaj-PROJECT.md; Phase 5 page 1 consumes those facts and commits the Composer pin before the first deploy.

   DEPLOY_PHP_VERSION="$(dep run "$BIN_PHP -r 'echo PHP_VERSION;'" --selector "alias=$DEPLOY_TARGET" 2>/dev/null | tail -1)"
   test -n "$DEPLOY_PHP_VERSION" || { echo "Could not read deploy PHP version — fix BIN_PHP before continuing"; exit 1; }
   printf 'Phase 5 carry-forward: pin Composer platform to deploy PHP %s from %s\n' "$DEPLOY_PHP_VERSION" "$BIN_PHP"
   # Expected: a non-empty deploy PHP version and a carry-forward note for Phase 5

   • ✅ Zaj-PROJECT.md records the deploy PHP version, web PHP, versioned CLI binary, and a Phase 5 carry-forward to write the Composer platform pin.

5. Commit the Deployer runtime facts with the deploy pipeline changes.

   git add deploy.php Zaj-PROJECT.md
   git commit -m "Configure Deployer PHP paths"
   # Expected: deploy.php plus non-secret runtime facts committed together

   • ✅ The Deployer PHP path and Zaj-PROJECT.md runtime facts are version-controlled together. Composer platform metadata is intentionally still untouched until Phase 5.

Verify PHP across all four surfaces before you deploy

Four PHP environments must agree, or the build passes and deploy:vendors fails at runtime. Shared hosting exposes two server-side PHPs (the versioned CLI bin/php you pin vs. the domain web SAPI), and a local PHP higher than the server can poison composer.lock with transitive dependencies the server cannot satisfy.

# LAYER 1 — what composer.json requires
grep '"php"' composer.json | head -1 | grep -oE '\^?[0-9]+\.[0-9]+'

# LAYER 2 — what deploy.php's bin/php points at, and what it reports
BIN_PHP=$(grep "set('bin/php'" deploy.php | grep -oE "/[^']+")
dep run "$BIN_PHP -v | head -1" --selector "alias=$DEPLOY_TARGET"

# LAYER 3 — diagnostic only: what the login shell's bare 'php' reports
dep run "php -v | head -1" --selector "alias=$DEPLOY_TARGET"

# LAYER 4 — your local php
php -v | head -1

Pattern	Status	Action
All four agree with composer.json, local matches server	✅ Safe	Deploy
Layer 2 matches but the domain web PHP is lower	⚠️ Runtime mismatch	Raise the domain web PHP selector, wait ~60s, re-run
Layer 4 is higher than the confirmed deploy PHP	🔴 Composer-drift trap	Record the Phase 5 platform-pin carry-forward; Phase 5 pins Composer before the first deploy
Layer 2 path missing	🔴 Stale bin/php	Re-discover the path

The domain web PHP version is controlled by the hosting control panel’s PHP setting, not only by the bin/php path. Store both in Zaj-PROJECT.md.

When the Phase 5 platform pin exposes a shipped-lock blocker

Setting Composer’s platform PHP changes Composer’s lock content hash. Phase 5 runs the pin plus the lock metadata refresh, then confirms the diff is only platform/hash metadata unless you intentionally resolve a package blocker.

If the dry run fails because a production package in the shipped lock requires a higher PHP than the confirmed deploy PHP, choose one path:

Decision	When to use	Command / action
Raise deploy PHP	Preferred on Hostinger/cPanel/Plesk when the domain can run a newer PHP	Set the domain to the compatible PHP, update Zaj-PROJECT.md, then let Phase 5 run the platform pin; no package version change
Downgrade the offending package	Domain PHP cannot be raised, and a compatible version still satisfies the parent constraint	composer update <vendor>/<pkg> -W, then rerun composer install --dry-run --no-dev under the pin
Escalate	No compatible package version exists, or the host cannot run the required PHP	Stop; do not deploy a lock that deploy:vendors cannot install

The blocker can come from any production package in the vendor’s shipped lock. Phase 5 uses composer prohibits php "$DEPLOY_PHP_VERSION" --locked --tree to find the parent chain before deciding whether to raise the server toolchain or downgrade an offending package.

Shared-hosting binary paths (Hostinger / cPanel pattern)

On shared hosting, PHP binaries are versioned and not on the default $PATH. Use full paths and match the version the control panel assigns to the domain:

• PHP: /opt/alt/php<XX>/usr/bin/php — <XX> is the host’s no-dot PHP suffix.
• Composer: typically /usr/local/bin/composer.

After changing the panel version, update bin/php to the matching /opt/alt/php<XX>/usr/bin/php and wait ~60s for the change to propagate.

5. Disable migrations for the first deploy

Running migrations before the vendor installer wizard causes schema conflicts. Comment the hook out for deploy #1, then re-enable after the installer runs in Phase 5.

1. Comment out the migrate hook.

   // after('deploy:vendors', 'artisan:migrate');

   • ✅ The migrate hook is commented out for the first deploy.

2. Confirm it’s disabled.

   grep -E "^\s*after\('deploy:vendors', 'artisan:migrate'\);" deploy.php \
     && echo "ENABLED" || echo "DISABLED — correct for first deploy"
   # Expected: "DISABLED — correct for first deploy"

   • ✅ The grep reports DISABLED — correct for first deploy.

6. Validate, then verify SSH access

Prove the file parses and the servers are reachable before any real deploy.

1. Syntax-check and parse deploy.php, then enumerate Deployer hosts without old remote-command syntax.

   php -l deploy.php                      # PHP syntax valid
   dep list 2>&1 | tail -30               # Deployer parses the file — expect 20+ tasks grouped by namespace
   # Expected: "No syntax errors detected", then a task catalog with no PHP/Deployer errors

   # Deployer 7 removed the old host-listing commands. These now fail:
   # dep config:hosts, dep hosts, dep list hosts
   # Correct host enumeration: parse deploy.php, then SSH-test the aliases from Zaj-PROJECT.md.
   grep -n "^host(" deploy.php
   DEPLOY_SSH_ALIAS="<selected-non-production-ssh-alias-from-Zaj-PROJECT>"
   PROD_SSH_ALIAS="<production-ssh-alias-from-Zaj-PROJECT>"
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$DEPLOY_SSH_ALIAS" 'pwd && php -v | head -1'
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$PROD_SSH_ALIAS" 'pwd && php -v | head -1'
   # Expected: host() rows match the deploy targets; both direct SSH checks exit 0

   • ✅ php -l is clean, dep list shows 20+ tasks, every host() grep-matches, and direct SSH reaches the selected aliases from Zaj-PROJECT.md.

2. Verify the Deployer graph with a dry deploy.

   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md
   dep deploy "$DEPLOY_TARGET" --plan | tee /tmp/dep-plan.txt
   grep -E 'deploy:vendors|deploy:symlink' /tmp/dep-plan.txt
   # Expected: dry-run plan parses the selected target and reaches deploy:vendors + deploy:symlink

   • ✅ dep deploy "$DEPLOY_TARGET" --plan reaches the vendor install and symlink steps without mutating the server.

3. Confirm the servers can reach GitHub and have the right tools.

   dep run "ssh -T git@github.com 2>&1 | tee /tmp/github-ssh-test.txt" --selector "alias=$DEPLOY_TARGET"
   dep run "grep -E 'successfully authenticated|Hi .*successfully authenticated' /tmp/github-ssh-test.txt && echo 'GitHub deploy key OK'" --selector "alias=$DEPLOY_TARGET"
       dep run "$BIN_PHP -v | head -1" --selector "alias=$DEPLOY_TARGET"              # match Zaj-PROJECT.md
       # Expected: GitHub banner confirms auth, and the server reports the confirmed deploy PHP version

   • ✅ GitHub authenticates from the server and the versioned PHP binary matches Zaj-PROJECT.md. Phase 5 owns the Composer platform pin.

If the SSH alias doesn’t exist

Create the ~/.ssh/config entry (host, port, user, key) before any deploy task. If GitHub auth fails from a server, generate a key there (ssh-keygen -t ed25519) and add the public key to Repo → Settings → Deploy keys (👤).

Deployer 7 command syntax

Use dep run '<command>' --selector "alias=<target>" for non-interactive remote commands. Use Deployer’s interactive SSH shell only when you truly need an interactive session; Deployer 7 rejects the older pattern where a target and command are passed together with a “Too many arguments” error.

Do not wrap dep deploy --plan in GNU timeout. --plan is local and should not hang; on macOS the GNU binary is gtimeout only if brew install coreutils is installed.

On fail — fix the layer that failed

• dep --version is not 7.x — install or select Deployer 7 before using this page’s command syntax.
• Direct ssh fails — fix ~/.ssh/config, host/user/port, or the authorized key before debugging deploy.php.
• GitHub auth fails from the server — add the server’s public deploy key in GitHub, then rerun the server-side ssh -T git@github.com proof.
• BIN_PHP reports the wrong version — update the hosting panel’s web PHP and Deployer bin/php; never pin Composer to the login-shell php.
• dep deploy --plan uses the wrong branch — fix the host’s branch value to match Zaj-PROJECT.md (develop for non-production, main for release/production in this playbook).

Troubleshooting

Symptom	Cause	Fix
dep: command not found	Composer bin not on PATH	Add to ~/.zshrc and source it
Cannot create symlink	Nested shared dirs	Keep only root folders (storage, not storage/app)
SSH timeout	Wrong port/IP	Match ~/.ssh/config
PENDING MIGRATIONS DETECTED	Unapplied migrations on server	Run manually or deploy with --allow-pending

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Deployer installed — dep --version returns Deployer 7.x; php -l deploy.php clean; dep list shows 20+ tasks.
• 🤖 Shared state correct — deploy.php shares storage/ + .env via add() (never set([])), with retention, an artisan:storage:link hook (so public/storage exists per release), and migrate/cache/queue hooks.
• 🤖 PHP confirmed — bin/php set to the confirmed domain deploy PHP, Zaj-PROJECT.md records web + CLI PHP, and the Phase 5 Composer platform-pin carry-forward is explicit.
• 🤖 First-deploy migrations off — the migrate hook is commented out.
• 🔀 SSH + dry run — direct SSH reaches the selected aliases, server GitHub auth works, and dep deploy "$DEPLOY_TARGET" --plan reaches the symlink step for the selected non-production target.

→Next step

Subdomains + SSL