1 · Pre-flight & provision host

TL;DR

Objective — get three things right before the first byte ships: the server PHP actually satisfies composer.json, the staging branch 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.

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). On shared hosting that setting — not bin/php — is what runs composer install, and only a person can change it.

Done when the plan previews cleanly, all three PHP layers satisfy composer.json, the staging branch is pushed, and the server has its deploy tree, .user.ini, and a placeholder shared/.env (APP_KEY empty).  ·  ⏱ ~45 min  ·  🔀 mixed (👤 PHP panel, 🤖 the rest).

Background

Everything in this phase rides on three things being right before the first byte ships: the server PHP actually satisfies composer.json, the staging branch 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 — system packages, the Admin-Server ops scripts, base hardening — lives in a separate server-setup track and is not repeated here. Add only a one-line pointer in your own runbook if you maintain that toolkit.

Steps

1. 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 staging --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 ↔ bin/php ↔ web SAPI.

   # 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 ssh staging "$BIN_PHP -v | head -1"
   
   # 3. What does the WEB SAPI run as? (this is what composer install actually uses)
   dep ssh staging "php -v | head -1"
   # Expected: all three PHP versions satisfy composer.json's require

   • ✅ bin/php, the web SAPI, and hPanel all satisfy composer.json’s require.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 confirms (and upgrades if needed) the web-serving PHP version in the hosting control panel — a per-domain dashboard setting an agent can’t change.

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

Pattern	Meaning	Action
bin/php, web SAPI, and hPanel all match composer.json	Safe to deploy	Proceed
bin/php matches but web SAPI is lower	Deploy will fail at deploy:vendors	Upgrade PHP in hPanel, wait ~60s, re-check
bin/php matches but hPanel shows lower	hPanel controls the web SAPI	Fix hPanel first
bin/php path doesn’t exist on the server	bin/php is stale	Re-run the SSH PHP discovery from Phase 4

A real deploy died exactly here

A live run failed at deploy:vendors with “requires php ^8.2 but your HTTP SAPI PHP version (8.1.x) does not satisfy that requirement.” The earlier check only verified Deployer’s bin/php, not the running web SAPI. The deploy aborted cleanly — smoke test never ran, the symlink never switched, the live release stayed up — but the round-trip was avoidable. bin/php alone is not sufficient on shared hosting, where multiple PHP binaries coexist and the panel selects the web one.

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)"]
  WS["web SAPI php<br/>(hPanel setting)"]
  CI["composer install<br/>(deploy:vendors)"]
  WS -->|actually runs| CI
  CJ -->|must be satisfied by| CI
  BP -.->|verified, but not the whole story| CI

2. 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, you’ll re-enable artisan:migrate — note it in your project log.

3. Spot-check optional-task 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.

4. Prepare the staging branch

Bring staging current with develop and push it, then confirm the host config and SSH still resolve.

1. Merge develop into staging and push.

   git status                      # expect: on develop, working tree clean
   git branch -a | grep staging    # exists?
   
   git checkout staging || git checkout -b staging
   git merge develop
   git push origin staging
   # Expected: staging is up to date with develop and pushed to origin

   • ✅ staging exists, is merged from develop, and is pushed to origin.

2. Confirm the host config and SSH resolve.

   grep -A5 "host('staging')" deploy.php   # correct hostname, remote_user, deploy_path
   ssh <staging-alias> "echo 'Staging SSH OK'"
   # Expected: deploy.php host block looks right; SSH prints "Staging SSH OK"

   • ✅ The host('staging') block is correct and SSH responds via the alias.

5. 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 staging
   # manual equivalent:
   ssh <staging-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.

6. Take a pre-deploy snapshot

Capture the current local DB before the first staging deploy so you have a rollback reference.

1. Snapshot the current local DB.

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

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

7. Scaffold the server

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

1. Create the server directory tree.

   ssh <staging-alias> "mkdir -p ~/domains/staging.yourapp.com/deploy/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 <staging-alias> 'cat > ~/domains/staging.yourapp.com/deploy/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 staging .env — always via the SSH alias, never raw user@IP:port.

   scp Admin-Local/1-Project/2-ProjectVault/.env.staging \
     <staging-alias>:~/domains/staging.yourapp.com/deploy/shared/.env
   ssh <staging-alias> "chmod 640 ~/domains/staging.yourapp.com/deploy/shared/.env"
   # Expected: .env uploaded and chmod 640 on the server

   • ✅ shared/.env is present and chmod 640.

   Optional — generate the .env from 1Password instead of a stored file

   If the project’s secrets live in 1Password (op vault list succeeds), generate the staging .env from a template at upload time rather than keeping a filled .env.staging on disk.

   op vault list &>/dev/null && echo "1Password available — use op inject" || echo "No 1Password — scp the stored .env"
   
   APP_VAULT="<project-vault>" op inject -i .env.tpl -o /tmp/.env.staging
   scp /tmp/.env.staging <staging-alias>:~/domains/staging.yourapp.com/deploy/shared/.env
   ssh <staging-alias> "chmod 640 ~/domains/staging.yourapp.com/deploy/shared/.env"
   rm -f /tmp/.env.staging
   # Expected: shared/.env placed with no plaintext secret left on local disk

   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.

8. 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 <staging-alias> "grep -inE '_HERE|your_|YOUR_|\[.*\]|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|FIXME|password_here' \
     ~/domains/staging.yourapp.com/deploy/shared/.env" 2>/dev/null
   ssh <staging-alias> "grep -E '^(DB_PASSWORD|MAIL_PASSWORD|REDIS_PASSWORD)=(\"\")?$' \
     ~/domains/staging.yourapp.com/deploy/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.

• 🤖 Plan previewed — dep deploy staging --plan pipeline shape looks right.
• 🔀 PHP triple-check passes — web SAPI / hPanel satisfy composer.json (👤 upgrade in panel if needed).
• 🤖 Deploy-safety flags confirmed — artisan:migrate disabled, clear_paths_strict true.
• 🤖 Optional tasks guarded — each carries a graceful-skip guard (no unguarded hard-fail).
• 🤖 staging branch ready — 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