6 · Commit & secure

TL;DR

Objective — make the working install durable and safe: commit the installer’s output (especially the storage/installed marker), document any author patches in the shipped vendor tree, verify deploy symlinks and shared_files, then lock down /install and /update with layered defense.

User part + done-when

👤 User part — add the Cloudflare WAF rule that blocks the installer routes at the edge (a dashboard/API-token action against your Cloudflare account). The git commits, vendor diff, symlink checks, and .htaccess rules are all terminal-runnable.

Done when storage/installed is tracked, Phase-3 changes are committed and pushed with a clean tree, _CUSTOMIZATIONS.md records vendor patches (or the skip reason), every deploy.php shared_files entry exists on disk and the storage symlink passes the HTTP content test, and /install + /update return 403 / are blocked at both layers.  ·  ⏱ ~30–45 min  ·  🔀 mixed (🤖 git + .htaccess, 👤 Cloudflare WAF).

Background

The app works — now make the state durable and safe. This page commits the installer’s artifacts, records vendor patches that would break on composer update, confirms the deploy symlinks survive a release, and slams the installer routes shut.

Steps

1. Review what the installer changed

See the installer’s footprint before staging anything.

1. Check the working tree.

   git status
   # Expected: modified storage/**/.gitignore, new storage/installed, maybe lock files + public/build/

   • ✅ The installer’s modified + new files are visible.

2. Backfill any missing storage/** ignore files (version-aware — Laravel 11+ and debugbar add new subdirs).

   for dir in storage/app storage/app/public storage/app/private \
     storage/framework storage/framework/cache storage/framework/cache/data \
     storage/framework/sessions storage/framework/testing storage/framework/views \
     storage/logs storage/debugbar; do
     [ -d "$dir" ] && [ ! -f "$dir/.gitignore" ] && printf '*\n!.gitignore\n' > "$dir/.gitignore"
   done
   # Expected: each existing storage subdir ends up with its "* / !.gitignore" file

   • ✅ Every existing storage/** directory carries a .gitignore.

storage/installed MUST be tracked

This marker tells the app “installation is complete — don’t show the wizard.” On first deploy to each server the installer runs once; after that the marker must persist so the wizard never reappears to the public. If it’s missing from git status, storage/.gitignore is blocking it:

grep -q "!installed" storage/.gitignore || echo "!installed" >> storage/.gitignore
git add storage/installed && echo "✅ tracked" || echo "❌ still blocked"

2. Stage, commit, push

Stage the marker, the installer-touched ignore files, lock files, and built assets, then push.

1. Stage the install artifacts.

   git add -A storage/
   git add composer.lock package-lock.json public/build/ 2>/dev/null
   # Expected: marker, ignore files, lock files, and build output staged

   • ✅ All install artifacts are staged.

2. Commit and push — single bundle for a first run, split by concern for a mixed rerun.

   git commit -m "Phase 3: Local dev environment + installer complete"
   git push origin "$(git rev-parse --abbrev-ref HEAD)"
   git status   # working tree clean
   # Expected: commit created, branch pushed, "nothing to commit, working tree clean"

   • ✅ The commit is pushed and the working tree is clean.

For a first run, a single commit reads cleanly. For a rerun that mixes a previous session’s staged work with today’s changes, split by concern:

Strategy	When
Single bundle	First run, or small rerun of the same concern
Split by concern	Previous session’s work is topically different (e.g. Boost install vs schema rebuild)

git push does not deploy

Pushing makes commits visible and may trigger PR-review CI, but the standard Phase 4 setup has no push-triggered deploy — dep deploy staging (run locally) is the canonical deploy path. ServerSync workflows are manual (workflow_dispatch) capture jobs, not push hooks. If unsure, push to a feature branch and open a PR.

3. Compare shipped vs fresh vendor

CodeCanyon authors frequently patch packages inside vendor/. Those patches vanish on composer update — so document them now.

1. Skip if there’s nothing to compare — log the skip reason if vendor/ was composer-installed from the lock file.

   find _Source -maxdepth 4 -type d -name vendor 2>/dev/null | head -1 || echo "no shipped vendor — skip"
   # Expected: a shipped-vendor path, or "no shipped vendor — skip"

   • ✅ Whether a shipped vendor/ exists to diff is established.

2. Install a fresh copy in a temp dir and diff against the shipped tree.

   TEMP_DIR=$(mktemp -d)
   cp composer.json composer.lock "$TEMP_DIR/"
   (cd "$TEMP_DIR" && composer install --no-scripts --no-autoloader 2>&1 | tail -5)
   
   diff -rq vendor/ "$TEMP_DIR/vendor/" 2>/dev/null | grep -v "^Only in $TEMP_DIR" | head -30
   [ -n "$TEMP_DIR" ] && [ -d "$TEMP_DIR" ] && rm -rf "$TEMP_DIR"
   # Expected: a list of differing/added files (author patches), or no output if clean

   • ✅ Author patches and additions are surfaced.

3. Record both in _CUSTOMIZATIONS.md at the project root — package, file, what changed, and a reminder to re-apply on update. This is the file the deploy pipeline reads before ever running composer update.

   • ✅ _CUSTOMIZATIONS.md documents every vendor patch (or the documented skip reason).

Skip if vendor was composer-installed

If the ZIP shipped no pre-built vendor/ (your vendor/ came from composer install against composer.lock), there’s nothing to compare. Log the skip reason in _CUSTOMIZATIONS.md and jump to §4. Differing files are author patches; files only in the shipped tree are author additions.

3b. Investigate (don’t delete) files tracked under storage/

Laravel’s storage/ holds runtime data, and Deployer swaps the release’s storage/ for a symlink on every deploy — so files committed under storage/ never reach the running app via the release copy. But deleting them blindly is dangerous: many vendor packages read runtime config from storage_path('<file>'), and git rm-ing such a file can break the package silently on the next run. The goal here is to investigate, not delete.

1. List the suspect files — everything tracked under storage/ that isn’t a standard marker.

   ALL=$(git ls-files storage/ 2>/dev/null)
   SUSPECT=$(echo "$ALL" | grep -vE '\.gitkeep$|\.gitignore$|^storage/installed$')
   [ -z "$SUSPECT" ] && echo "✅ Only standard markers tracked — nothing to investigate" \
     || { echo "Investigate:"; echo "$SUSPECT" | sed 's/^/  ⚠️  /'; }
   # Expected: either the all-clear, or a short list of files to scan

   • ✅ The suspect list (if any) is known.

2. For each suspect, scan for a storage_path() reference across vendor, in-tree packages, and project code.

   FILE="storage/<SUSPECT_FILE>"; BASENAME=$(basename "$FILE")
   grep -rn "$BASENAME\|storage_path.*$BASENAME" vendor/ packages/ app/ config/ routes/ resources/ 2>/dev/null | head -10
   wc -c "$FILE" 2>/dev/null; head -3 "$FILE" 2>/dev/null
   # Expected: any line that reads storage_path('<basename>') means the file is LIVE

   • ✅ Each suspect is classified by where it is read.

A read alone proves liveness — do NOT try to prove “it’s unused”

The safe rule: if storage_path('<basename>') appears anywhere in vendor/, packages/, or project code, the file is live — keep it tracked. You do not also need to find a write operation; vendor packages often assign the path to a property and write through it later.

$this->ignoreFilePath = storage_path('<basename>');          // assignment — has the basename
file_put_contents($this->ignoreFilePath, json_encode($x));   // write — basename never appears

grep 'file_put_contents.*<basename>' returns empty, but the file is definitively live. Empty content is not proof of “unused” either — packages seed [], {}, or "" state files and populate them later. Default: keep tracked, and log the decision + read site in _CUSTOMIZATIONS.md so the next vendor-update rerun does not re-investigate from scratch.

4. Verify deployment symlinks & shared files

Page 3 created public/storage (and any addon symlinks) locally. Deployer must recreate them on every release, and any shared_files entry that doesn’t exist on disk breaks the first deploy.

1. Confirm the local symlinks exist.

   ls -la public/ | grep "^l"   # expect storage (+ packages/addons if used)
   # Expected: at least the storage symlink, plus any addon symlinks from page 3

   • ✅ public/storage (and any addon symlinks) are present.

2. Verify every deploy.php shared_files entry exists on disk.

   php -r '
   $src = file_get_contents("deploy.php");
   $c = ["shared_files" => []];
   foreach (["set", "add"] as $fn) {
     if (preg_match_all("/\\b".$fn."\\s*\\(\\s*[\'\"]shared_files[\'\"]\\s*,\\s*\\[(.*?)\\]\\s*\\)/s", $src, $ms, PREG_SET_ORDER)) {
       foreach ($ms as $m) {
         preg_match_all("/[\'\"]([^\'\"]+)[\'\"]/", $m[1], $p);
         $c["shared_files"] = array_merge($c["shared_files"], $p[1]);
       }
     }
   }
   $c["shared_files"] = array_values(array_unique($c["shared_files"]));
   if (!$c["shared_files"]) { fwrite(STDERR, "❌ ABORT: no shared_files paths parsed from deploy.php\n"); exit(1); }
   foreach (($c["shared_files"] ?? []) as $f) echo $f, "\n";
   ' | while IFS= read -r f; do
     [ -f "$f" ] && echo "✅ $f" || echo "❌ $f — MISSING; first deploy will fail"
   done
   # Expected: at least one path parsed; a ✅ per shared_files entry; fix any ❌ before deploying

   • ✅ Every shared_files entry resolves to a real file.

3. Prove the storage symlink serves a real file end-to-end.

   TEST="storage/app/public/test-$(date +%s).txt"; echo "ok-$(date +%s)" > "$TEST"
   URL="https://[PROJECT_NAME].test/storage/$(basename "$TEST")"
   [ "$(curl -s "$URL")" = "$(cat "$TEST")" ] && echo "✅ symlink + nginx wired" || echo "❌ chain broken"
   rm -f "$TEST"
   # Expected: "✅ symlink + nginx wired" (HTTP 200 with matching content)

   • ✅ The served content matches the file — symlink + nginx chain is wired.

Every shared_files entry must exist on disk

Deployer’s first-deploy seed copies each shared_files entry from the release into shared/. If the file doesn’t exist locally, the seed fails and every later deploy is broken. Fix a ❌ by creating the file (touch storage/<name> for a vendor state file) or removing the dead entry. shared_dirs are more forgiving — Deployer creates missing ones empty, so a local absence there is informational only. Confirm deploy.php handles your addon mechanism (page 3 §2): symlink-based systems need an ln -sfn ../<dir> public/<dir> hook; Modules/ apps need php artisan module:publish-assets after symlinking. HTTP 200 with matching content is the only passing state for the symlink test (403 on the bare directory URL is normal — directory browsing is off).

A file is in shared_files OR inside a shared_dirs dir — never both

deploy.php ships shared_dirs: ['storage'] by default, so every file under storage/ is already persistent across releases — Deployer creates shared/storage/ once and symlinks it into every release. Adding a storage/ file to shared_files too creates a symlink-resolution cycle and aborts the deploy:

1. deploy:shared processes shared_dirs: ['storage'] → symlinks release/storage → shared/storage.
2. It then processes shared_files: ['storage/<file>'] → tries to seed shared/storage/<file> via the release-side path release/storage/<file>.
3. But release/storage is already a symlink to shared/storage, so the path loops.
4. Error: touch: cannot touch '.../shared/storage/<file>': Too many levels of symbolic links.

The rule: since storage/ is in shared_dirs, any file under it is shared automatically. Do not list it in shared_files. shared_files is only for files outside every shared_dirs directory, and .env has its own mechanism.

# 1. Remove the conflicting storage/<file> entry from deploy.php shared_files
# 2. It still persists via shared_dirs: ['storage']
# 3. Clean up the partially-created shared file on the server, if any
dep ssh staging "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/<FILENAME>"
# 4. Re-run the deploy
dep deploy staging
# Expected: deploy:shared completes; no "Too many levels of symbolic links"

Edits to a tracked storage/ file won’t deploy — they’re shadowed by the symlink

Because release/storage is a symlink to shared/storage/, the first deploy seeds the git-tracked storage/ files into shared/storage/, and from the second deploy onward the running app reads through the symlink — the release copy is never read again.

So if you edit a git-tracked file under storage/, commit, and deploy, the running app still reads the old shared/storage/<file>. Your edit silently won’t take effect until you either SSH in and update shared/storage/<file> by hand, or delete shared/storage/<file> on the server so Deployer’s first-deploy seed re-runs.

If a file must be deployable, move it out of storage/ to a root-level directory that is not in shared_dirs, then add that path to shared_files.

5. Lock down /install and /update

Left open, these routes let anyone reset the app or alter its schema. Use layered defense — two independent layers that block before PHP boots.

1. Layer 1 — .htaccess. Add these right after RewriteEngine On in public/.htaccess, before the Laravel rewrite block.

   # Block installer + updater routes at Apache level — PHP never loads.
   RewriteRule ^install(/.*)?$ - [F,L]
   RewriteRule ^update(/.*)?$ - [F,L]
   RewriteRule ^upgrade-script$ - [F,L]
   RewriteRule ^update-manual(/.*)?$ - [F,L]
   # If your app has a separate /updater package, uncomment:
   # RewriteRule ^updater(/.*)?$ - [F,L]

   • ✅ The installer/updater rewrite rules sit before the Laravel block.

2. Commit the .htaccess change.

   git add public/.htaccess && git commit -m "Block /install and /update routes at Apache level"
   # Expected: the .htaccess rule commit is created

   • ✅ public/.htaccess is committed.

^install(/.*)?$ matches /install, /install/, and /install/anything — but not /install-extension (a legitimate admin route in some apps). [F] returns 403 instantly.

Why not middleware?

Middleware needs the full framework to boot first — on heavy CodeCanyon apps that risks 500s during deploys when the DB may be briefly unreachable, and the installer package’s own excluded_middleware can conflict. For unconditionally blocking 2–3 rare routes, .htaccess is simpler and more reliable.

Now add the edge layer — a Cloudflare WAF rule that blocks the same paths for all public internet traffic.

Who does this

👤 User adds the Cloudflare WAF custom rule against their Cloudflare account (the OAuth MCP has no WAF write scope — it’s a dashboard or $CF_API_TOKEN REST-API action a person authorizes, not an agent step).

1. Layer 2 — Cloudflare WAF. Check the rule count first (free plan allows 5 custom rules), then add a rule expression that blocks the same path prefixes (http.request.uri.path contains "/install", /update, …) with a block action.

   • ✅ A Cloudflare WAF rule blocks the installer/updater paths at the edge.

2. Verify both layers from the terminal.

   curl -sI -o /dev/null -w "install: HTTP %{http_code}\n" https://[PROJECT_NAME].test/install
   curl -sI -o /dev/null -w "update:  HTTP %{http_code}\n" https://[PROJECT_NAME].test/update
   # Expected: 403 (Apache) or blocked at the edge — a 200 means a layer isn't active

   • ✅ Both routes return 403 / are blocked.

To temporarily allow access for a legitimate update: comment out the .htaccess rules via SSH (and pause the WAF rule), run the update, then restore both.

Checklist

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

• 🤖 Marker tracked — storage/installed tracked; all storage/**/.gitignore files present.
• 🤖 Committed + pushed — Phase-3 changes committed and pushed; working tree clean.
• 🤖 Patches documented — _CUSTOMIZATIONS.md records vendor patches (or the documented skip reason).
• 🤖 Deploy paths verified — every deploy.php shared_files entry exists; storage symlink passes the HTTP content test.
• 🔀 Routes locked — /install and /update return 403 / are blocked at both layers (👤 WAF + 🤖 .htaccess).

→Next step

Optional tooling