1 · Pre-flight & provision host

TL;DR

Objective — get four things right before the first byte ships: the Phase 4 handoff is complete, Composer is pinned to the confirmed deploy PHP, the selected non-production branch/target is current, and the server scaffolding (deploy tree, PHP limits, .env) exists — because a pre-flight failure is cheap and a deploy:vendors failure three minutes into a release is not.

Steps at a glance:

1. Consume the Phase 4 handoff and pin Composer — Phase 4 confirms the deploy PHP; this page writes the Composer platform pin and refreshes the lock metadata before the first live deploy.
2. Run the canonical pre-flight — Do not deploy blind. Preview the full pipeline, then confirm the PHP version the server actually runs — not just the binary Deployer points at.
3. Confirm the deploy-safety flags — The recipe disables and enables a few tasks deliberately. Confirm the flags are set the way the pipeline expects before you trust the plan.
4. Spot-check skip-policy gating — Optional tasks (AWS backup, Atlas, ZajModule migrations, Livewire publish, Sentry/Slack/Discord) must each carry a graceful-skip guard so a feature you haven’t configured can’t hard-fail the deploy.
5. Prepare the non-production branch — Bring the source branch from Zaj-PROJECT.md current with develop and push it, then confirm the host config and SSH still resolve.
6. Clear the server composer cache — Shared hosts carry stale composer cache from prior projects — even an identical composer.lock can pull old cached package versions with extra migration files.
7. Take a pre-deploy snapshot — Capture the current local DB before the first non-production deploy so you have a rollback reference.
8. Scaffold the server — Create the deploy directory tree, set the PHP limits the installer needs, then place the selected environment’s .env — three commands that prepare the host for its first release.
9. Scan the .env for placeholders — A deploy fails if .env still has unfilled placeholders or empty required values. Catch them before you ship.

User part + done-when

👤 User part — one dashboard action: confirm (and if needed upgrade) the web-serving PHP version in the hosting control panel (hPanel → Websites → [domain] → Advanced → PHP Configuration). The agent verifies the Deployer CLI PHP / Composer runtime from deploy.php; the panel or installer Requirements screen verifies the web SAPI that handles browser requests.

Done when the Phase 4 handoff is consumed, Composer platform metadata matches the confirmed deploy PHP, the plan previews cleanly, the Deployer PHP / Composer runtime satisfies composer.json, the selected non-production branch is pushed, and the server has its deploy tree, .user.ini, and a placeholder shared/.env (APP_KEY empty). The web SAPI is captured from hPanel now and from the installer Requirements screen on page 4.  ·  ⏱ ~45 min  ·  🔀 mixed (👤 PHP panel, 🤖 the rest).

Background

Everything in this phase rides on four things being right before the first byte ships: the Phase 4 handoff is complete, the server PHP actually satisfies composer.json, the selected non-production branch/target is current, and the server scaffolding (deploy tree, PHP limits, .env) exists. A pre-flight failure is cheap; a deploy:vendors failure three minutes into a release is not.

Per-server bootstrap is out of scope

This page assumes the host itself is already reachable (SSH alias works, Deployer + SSL verified in Phase 4). The once-per-server toolkit — monitoring cron, MD5 baselines, deploys/ops webhooks — lives in Set up shared hosting. The tracked app-playbook gate is Phase 3 Step 7 · Shared-hosting readiness; do not enter Phase 4 or Phase 5 unless status.sh exits 0, Admin-Server cron logs are fresh with no STALE rows, monitored-paths.conf includes ~/.ssh/authorized_keys plus this app path, and alerting is either proven with a synthetic ops alert or explicitly recorded as inactive.

Staging and production may be on different hosting accounts

Don’t assume one hosting login spans every environment — a common topology is non-production on one account, production on a different account (separate logins, separate API tokens, no cross-account visibility). Capture the hosting account per environment row alongside the SSH alias/IP in Zaj-PROJECT.md, and give each account its own token/MCP (op://General-Dev/Hostinger-nonprod/HOSTINGER_API_TOKEN vs op://General-Dev/Hostinger-prod/HOSTINGER_API_TOKEN). A connected hosting MCP authed to the wrong account silently operates on the wrong server. Full topology guidance: Prerequisites §multi-account hosting.

Steps

0. Load the selected environment row

Read Zaj-PROJECT.md first and choose the non-production environment row you are deploying to. If the project has more than one non-production target, do not guess — use the row the operator selected for this pass.

ENV_KEY="staging-primary"        # example; use the real Zaj-PROJECT.md row key
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer host key from Zaj-PROJECT.md
SOURCE_BRANCH="develop"          # example; use the source branch from Zaj-PROJECT.md
SSH_ALIAS="<non-prod-alias>"     # SSH alias from Zaj-PROJECT.md
HOSTING_ACCOUNT="<hostinger-account-ref>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match one Zaj-PROJECT.md non-production row, including the hosting account

• ✅ The environment key, deploy target, source branch, hosting account, SSH alias, domain, and deploy path all match Zaj-PROJECT.md.

1. Consume the Phase 4 handoff and pin Composer

Phase 4 confirmed the deploy PHP and authored the pipeline. This step writes the Composer platform pin for the selected non-production target and proves the lock still installs before any server mutation happens.

1. Verify the Phase 4 handoff evidence exists.

   test -f deploy.php && php -l deploy.php
   dep deploy "$DEPLOY_TARGET" --plan 2>&1 | grep -E 'deploy:vendors|deploy:symlink'
   grep -n "set('bin/php'" deploy.php
   # Expected: deploy.php parses, the plan reaches vendors + symlink, and bin/php is configured

   • ✅ Phase 4’s AUTHOR proof is present for the selected target.

2. Pin Composer to the confirmed deploy PHP and refresh lock metadata.

   BIN_PHP=$(grep "set('bin/php'" deploy.php | grep -oE "/[^']+")
   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 pinning"; exit 1; }
   
   composer config platform.php "$DEPLOY_PHP_VERSION"
   composer update --lock
   composer prohibits php "$DEPLOY_PHP_VERSION" --locked --tree
   composer check-platform-reqs --lock --no-dev
   composer install --dry-run --no-dev
   git diff -- composer.json composer.lock
   # Expected: platform.php matches the confirmed deploy PHP; lock metadata refreshed;
   #           dry-run succeeds; no package version changes unless intentionally resolving a blocker

   • ✅ composer.json and composer.lock agree with the confirmed deploy PHP, and composer install --dry-run --no-dev succeeds.

3. Commit the platform pin before the first deploy.

   git add composer.json composer.lock Zaj-PROJECT.md
   git commit -m "Pin Composer platform for non-production deploy"
   # Expected: one commit with the Composer platform/lock metadata and project-state update

   • ✅ Composer platform metadata and Zaj-PROJECT.md are version-controlled before the first live deploy.

If the pin exposes a shipped-lock blocker

If composer install --dry-run --no-dev 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	Action
Raise deploy PHP	Preferred when the host can run the newer PHP	Set both domain web PHP and Deployer bin/php to the compatible version, update Zaj-PROJECT.md, then rerun this section
Downgrade the offending package	The host cannot raise PHP, and a compatible version still satisfies the parent constraint	Resolve with Composer, then rerun the checks under the pin
Escalate	No compatible package version exists, or the host cannot run the required PHP	Stop; do not deploy a lock that the server cannot install

2. Run the canonical pre-flight

Do not deploy blind. Preview the full pipeline, then confirm the PHP version the server actually runs — not just the binary Deployer points at.

1. Preview the plan.

   # Deployer 7 uses --plan; the old --dry-run was removed and errors out
   dep deploy "$DEPLOY_TARGET" --plan 2>&1 | tail -60
   # Expected: a ~40–50 task pipeline including the gates that matter

   You should see a ~40–50 task pipeline. The exact list depends on enabled features (Atlas, AWS backup, Sentry, Slack/Discord, module migrations, Livewire publish), but the canonical shape includes the gates that matter:

   deploy:check_existing_pending   ← BLOCKS if staging has pending migrations
   deploy:verify_clear_paths       ← BLOCKS if a sensitive file survives clear_paths
   deploy:vendors                  ← composer install — fails here on PHP mismatch
   deploy:verify_migrations
   deploy:smoke_test               ← BLOCKS before the symlink switch
   deploy:symlink                  ← atomic cutover
   deploy:health_check             ← BLOCKS after symlink; auto-rollback on failure

   • ✅ The plan previews a sane ~40–50 task pipeline with the gates above present.

2. Triple-check PHP — composer.json ↔ Deployer bin/php ↔ Composer runtime, with the web SAPI captured by hPanel now and page 4 later.

   # 1. What does composer.json require?
   grep '"php"' composer.json | head -1
   
   # 2. What does deploy.php point bin/php at, and what does that binary report?
   BIN_PHP=$(grep "set('bin/php'" deploy.php | grep -oE "/[^']+")
   dep run "$BIN_PHP -v | head -1" --selector "alias=$DEPLOY_TARGET"
   
   # 3. Does bin/composer run through the same configured PHP?
   grep -n "set('bin/composer'.*bin/php" deploy.php
   dep run "$BIN_PHP -r 'echo PHP_VERSION.PHP_EOL;'" --selector "alias=$DEPLOY_TARGET"
   # Expected: composer.json's PHP requirement is satisfied by the configured deploy PHP,
   #           and bin/composer is wired through bin/php (not bare login-shell php)

   • ✅ bin/php satisfies composer.json, and bin/composer is wired through bin/php.

Then cross-check the control panel: hPanel → Websites → [domain] → Advanced → PHP Configuration. On shared hosting the web-serving PHP is set there per-domain — not by bin/php in deploy.php.

Who does this

🔀 User + Agent — 👤 the user authorizes hosting-panel access and any PHP-version change. 🤖 With an authorized browser session, the agent can navigate the panel, read the selected web PHP, capture evidence, and verify it again on the installer Requirements screen.

Use the table to read the result of the triple-check:

Pattern	Meaning	Action
bin/php and bin/composer satisfy composer.json	Safe for deploy:vendors	Proceed
bin/composer does not include bin/php	Composer may run under login-shell PHP	Fix deploy.php, re-run the plan
hPanel/web SAPI is lower than the app needs	Browser requests or installer checks may fail	Upgrade PHP in hPanel, wait ~60s, re-check
bin/php path doesn’t exist on the server	bin/php is stale	Re-run the SSH PHP discovery from Phase 4

Do not trust login-shell php -v

On shared hosting, the default shell php is often the login-shell PHP, not the version Deployer uses for Composer and not necessarily the web SAPI. Treat it as informational only. The deploy truth is deploy.php’s bin/php / bin/composer; the web-request truth is hPanel now and the installer Requirements screen on page 4.

The three layers and which one actually runs composer install:

flowchart TD
  CJ["composer.json<br/>requires PHP ^8.x"]
  BP["deploy.php bin/php<br/>(CLI binary)"]
  BC["deploy.php bin/composer<br/>(must use bin/php)"]
  WS["web SAPI php<br/>(hPanel + installer screen)"]
  CI["composer install<br/>(deploy:vendors)"]
  BP --> BC
  BC --> CI
  CJ -->|must be satisfied by| CI
  WS -.->|browser request truth| CI

3. Confirm the deploy-safety flags

The recipe disables and enables a few tasks deliberately. Confirm the flags are set the way the pipeline expects before you trust the plan.

1. Confirm the three deploy-safety flags.

   grep -n "artisan:migrate.*disable" deploy.php   # expect: task('artisan:migrate')->disable();
   grep -n "clear_paths_strict" deploy.php          # expect: set('clear_paths_strict', true);
   grep -n "atlas_enabled" deploy.php               # expect: set('atlas_enabled', true);
   # Expected: each grep prints its matching line

   • ✅ artisan:migrate is disabled, clear_paths_strict is true, and atlas_enabled is set.

Why these “look unsafe” but aren’t

artisan:migrate is disabled because CodeCanyon installer apps own their migration lifecycle — the web installer runs migrations once. atlas_enabled=true is safe because deploy:atlas_preflight has a runtime gate that skips when the Atlas CLI isn’t installed (config flag + capability check = graceful degradation). If you later add project (_zaj) migrations, re-enable artisan:migrate and record the deploy-lifecycle change in Zaj-CUSTOMIZATIONS.md.

4. Spot-check skip-policy gating

Optional tasks (AWS backup, Atlas, ZajModule migrations, Livewire publish, Sentry/Slack/Discord) must each carry a graceful-skip guard so a feature you haven’t configured can’t hard-fail the deploy. Confirm each guards on missing config.

1. Scan each optional task for a skip guard.

   for t in deploy:aws_backup deploy:atlas_preflight deploy:zajmodule_migrations \
            livewire:publish_assets sentry:release slack:notify:success; do
     echo "=== $t ==="
     awk -v t="$t" '
       $0 ~ "task(\047" t "\047" { grab=1 }
       grab && /^task\(/ && $0 !~ "task(\047" t "\047" { exit }
       grab { print }
     ' deploy.php \
       | grep -E "if \(!get\(|if \(empty|NOT_FOUND|return;" | head -3 | sed 's/^/  /'
   done
   # Expected: each task prints at least one if (!get('..._enabled')) / if (empty(...)) / NOT_FOUND … return guard

   • ✅ Every optional task prints at least one graceful-skip guard; none is unguarded.

A task with zero guards may abort the pipeline when its feature isn’t configured — read its full body before you deploy.

5. Prepare the selected non-production branch

Bring the selected source branch from Zaj-PROJECT.md current with develop and push it, then confirm the host config and SSH still resolve.

1. Confirm the selected branch matches the Deployer host block, then push it.

   git status --short              # expect: clean before branch work
   git fetch origin develop "$SOURCE_BRANCH" --no-tags
   
   DEPLOY_BRANCH=$(awk -v host="host('$DEPLOY_TARGET')" '
     $0 ~ host { in_host=1 }
     in_host && /set\('\''branch'\''/ {
       match($0, /set\('\''branch'\'', *'\''([^'\'']+)/, m); print m[1]; exit
     }
     in_host && /^host\('/ && $0 !~ host { exit }
   ' deploy.php)
   
   test -n "$DEPLOY_BRANCH" || { echo "STOP — no branch set for $DEPLOY_TARGET in deploy.php"; exit 1; }
   test "$DEPLOY_BRANCH" = "$SOURCE_BRANCH" || {
     echo "STOP — Zaj-PROJECT says $SOURCE_BRANCH, deploy.php says $DEPLOY_BRANCH";
     exit 1;
   }
   
   git checkout "$SOURCE_BRANCH" || git checkout -b "$SOURCE_BRANCH" "origin/$SOURCE_BRANCH"
   if [ "$SOURCE_BRANCH" != "develop" ]; then
     git merge develop
   fi
   git push -u origin "$SOURCE_BRANCH"
   # Expected: selected non-production branch matches deploy.php and is pushed to origin

   • ✅ The selected non-production branch matches the Deployer host’s branch setting and is pushed to origin.

2. Confirm the host config and SSH resolve.

   grep -A5 "host('$DEPLOY_TARGET')" deploy.php   # correct hostname, remote_user, deploy_path
   ssh "$SSH_ALIAS" "echo 'Non-production SSH OK'"
   # Expected: deploy.php host block looks right; SSH prints "Non-production SSH OK"

   • ✅ The selected Deployer host block is correct and SSH responds via the alias.

6. Clear the server composer cache (first deploy only)

Shared hosts carry stale composer cache from prior projects — even an identical composer.lock can pull old cached package versions with extra migration files.

1. Clear the server’s composer cache.

   dep clear_composer_cache "$DEPLOY_TARGET"
   # manual equivalent:
   ssh "$SSH_ALIAS" 'CACHE_DIR=~/.cache/composer/files; [ -d "$CACHE_DIR" ] && mv "$CACHE_DIR" "${CACHE_DIR}_backup_$(date +%Y%m%d%H%M%S)"; mkdir -p "$CACHE_DIR"; find "$CACHE_DIR" -mindepth 1 | wc -l'
   # Expected: 0

   • ✅ The server composer cache is empty (0).

Run this on a first deploy, after major composer.lock changes, or when you hit mysterious migration conflicts.

7. Take a pre-deploy snapshot

Capture the current local DB before the first non-production deploy so you have a rollback reference.

1. Snapshot the current local DB.

   SNAP="Admin-Local/1-Project/6-Schema/2-Snapshots/$(date +%Y-%m-%d)-pre-${ENV_KEY}"
   mkdir -p "$SNAP"
   cp Admin-Local/1-Project/6-Schema/1-Current/local.sql "$SNAP/local.sql"
   echo "Pre-first-${ENV_KEY}-deploy snapshot" > "$SNAP/notes.md"
   # Expected: a dated snapshot dir holding local.sql + notes.md

   • ✅ A dated pre-$ENV_KEY snapshot exists with local.sql and notes.md.

8. Scaffold the server

Create the deploy directory tree, set the PHP limits the installer needs, then place the selected environment’s .env — three commands that prepare the host for its first release.

1. Create the server directory tree.

   ssh "$SSH_ALIAS" "mkdir -p $DEPLOY_PATH/shared/storage"
   # Expected: no output (directories created)

   • ✅ deploy/shared/storage exists on the server.

2. Set the PHP limits the installer needs.

   # Feed the heredoc to the LOCAL ssh's stdin (EOF at column 0 here), and let
   # ssh forward it to the remote `cat`. Keep the heredoc outside the remote
   # quoted command so the terminator is controlled by the local shell.
   ssh "$SSH_ALIAS" "cat > $DEPLOY_PATH/shared/.user.ini" <<'EOF'
   max_execution_time = 300
   memory_limit = 512M
   max_input_time = 300
   upload_max_filesize = 64M
   post_max_size = 64M
   EOF
   # Expected: shared/.user.ini written with the installer limits

   • ✅ shared/.user.ini sets max_execution_time = 300 and the upload limits.

3. Place the selected environment .env — always via the SSH alias, never raw user@IP:port. Prefer rendering from .env.tpl and 1Password so no filled env file lives on disk.

   TMP_ENV="$(mktemp)"
   op inject -f -i .env.tpl -o "$TMP_ENV"
   ssh "$SSH_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
   ssh "$SSH_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
   shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
   test ! -f "$TMP_ENV"
   # Expected: shared/.env has a non-zero byte count, mode 640, and the local temp file is gone

   • ✅ shared/.env is present, chmod 640, and no rendered temp file remains locally.

   Legacy/resume fallback — stored file

   If the project predates .env.tpl / op inject, use the stored file once, then migrate it into the secrets-manager template:

   scp "Admin-Local/1-Project/2-Vault/.env.${ENV_KEY}" "$SSH_ALIAS:$DEPLOY_PATH/shared/.env"
   ssh "$SSH_ALIAS" "chmod 640 $DEPLOY_PATH/shared/.env"
   # Expected: shared/.env placed; follow up by moving values into 1Password + .env.tpl

   Leave APP_KEY empty either way — the first-deploy health check generates it.

Use the alias for scp

The alias carries the key, port, and user from ~/.ssh/config. Raw scp user@IP:path fails with “Permission denied” on key-only servers because it falls back to password auth.

9. Scan the .env for placeholders

A deploy fails if .env still has unfilled placeholders or empty required values. Catch them before you ship.

1. Scan for placeholders and empty required secrets.

   ssh "$SSH_ALIAS" "grep -inE '_HERE|your_|YOUR_|\[.*\]|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|FIXME|password_here' \
     '$DEPLOY_PATH/shared/.env'" 2>/dev/null
   ssh "$SSH_ALIAS" "grep -E '^(DB_PASSWORD|MAIL_PASSWORD|REDIS_PASSWORD)=(\"\")?$' \
     '$DEPLOY_PATH/shared/.env'" 2>/dev/null
   # Expected: no output (no placeholders, no empty required secrets)

   • ✅ Neither scan returns a line — no placeholders, no empty required secrets.

If a service isn’t ready yet (e.g. Redis/Upstash), set it to a local driver temporarily and switch later:

CACHE_DRIVER="file"      # Laravel 11+: CACHE_STORE="file"
SESSION_DRIVER="file"
QUEUE_CONNECTION="sync"

Leave APP_KEY empty here

The first-deploy health check generates APP_KEY. Pre-filling it (or pasting a local key) risks invalidating sessions and encryption later. Use placeholders only — real secrets come from your vault, never from a guide or a commit.

Checklist

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

• 🤖 Phase 4 handoff consumed — deploy.php parses, dep --plan reaches vendors + symlink, and confirmed bin/php is present.
• 🤖 Composer platform pinned — Composer platform matches the confirmed deploy PHP, lock metadata refreshed, dry-run install passes, and the commit is made before first deploy.
• 🤖 Plan previewed — dep deploy "$DEPLOY_TARGET" --plan pipeline shape looks right.
• 🔀 PHP triple-check passes — Deployer bin/php / bin/composer satisfy composer.json; hPanel web SAPI checked now and installer Requirements screen recorded on page 4.
• 🤖 Deploy-safety flags confirmed — artisan:migrate disabled, clear_paths_strict true.
• 🤖 Optional tasks guarded — each carries a graceful-skip guard (no unguarded hard-fail).
• 🤖 Source branch ready — selected non-production source branch from Zaj-PROJECT.md merged from develop and pushed; SSH + host config verified.
• 🤖 Cache cleared + snapshot taken — composer cache cleared (first deploy); pre-deploy snapshot saved.
• 🤖 Server scaffolded — deploy/shared/storage tree exists; shared/.user.ini sets installer limits.
• 🤖 shared/.env placed — chmod 640, no placeholders, APP_KEY empty, APP_DEBUG=false.

→Next step

DNS + SSL