3 · First release

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 3 · First release
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/03-first-release/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 5
- part_number: 3 (legacy stepNumber frontmatter)
- legacy_step_number: 3
- est_time: ~30–45 min
- description: Run the atomic first deploy, confirm APP_KEY and clear caches with the versioned PHP binary, verify the Deployer directory tree and the .env symlink (a 5-second check that prevents a 90-minute outage), confirm demo content, then loosen permissions for the installer.
- tags: codecanyon, laravel, deployer, release

## Execution rules (binding)
- This is Part 3 of phase 5 (~30–45 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 3 · First release

## TL;DR

**Objective** — ship the app's first atomic release and prove it booted correctly: force first-deploy-safe cache/session/queue drivers when the vendor defaults to database-backed drivers, confirm `APP_KEY`, clear caches with the versioned PHP binary, verify the Deployer tree and the `.env` symlink (a 5-second check that prevents a 90-minute outage), confirm seeded storage assets survived `shared_dirs`, then loosen permissions for the installer.

**Steps at a glance:**
0. **Set first-deploy-safe runtime drivers** — Some vendors default cache/session/queue to database tables the
   installer has not created yet. Use file/sync drivers until the installer completes.
1. **Dry-run, then deploy** — Preview the pipeline one last time, then run the atomic release. The symlink flips
   only on a passing smoke test.
2. **Confirm APP_KEY and clear caches** — Confirm the health check generated `APP_KEY`, remove any stale install
   lock, then clear caches with the versioned PHP binary.
3. **Verify the Deployer directory structure** — Confirm Deployer laid out the atomic release tree as expected.
4. **Verify the `.env` symlink** — `shared_files` controls which files Deployer symlinks from `shared/` into
   each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's
   default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently
   loading the wrong.
5. **Verify demo/default content deployed** — CodeCanyon apps ship demo content (images, avatars, themes, sample
   data) in app-specific locations.
6. **Loosen permissions for the installer** — The web installer requires writable paths. This is a deliberate,
   temporary loosening — it gets hardened on page 4.

:::note[User part + done-when]
**👤 User part** — almost none: this step is entirely SSH/CLI-runnable. A person only needs to read the `.env`-symlink BLOCKER outcome to decide whether to STOP.

**Done when** first-deploy-safe drivers are active, `dep deploy "$DEPLOY_TARGET"` succeeds for the selected non-production row in `Zaj-PROJECT.md`, `current` symlinks to the new release, `APP_KEY` is present, `current/.env` resolves to `shared/.env`, seeded storage/media content is present in shared storage, and permissions are loosened for the installer. &nbsp;·&nbsp; **⏱ ~30–45 min** &nbsp;·&nbsp; 🤖 agent-runnable.
:::

## Background

The payoff of Phase 4 — the app's first atomic release. Deployer flips the `current` symlink **only** after the smoke test passes, so a failed build never touches the live release.

:::note[First live deploy proof lives here]
Phase 4 authored the Deployer and GitHub Actions artifacts. This page is the first [RUN-LIVE] deploy proof: run the release directly with Deployer, or trigger the CI deploy workflow for the selected non-production target and verify it reaches the same symlink/current checks below. Do not backfill that proof into Phase 4.
:::

Reuse the environment variables from page 1, or reload them from `Zaj-PROJECT.md` before running commands:

```bash
ENV_KEY="staging-primary"        # example; use the selected Zaj-PROJECT.md row
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer target from that row
SSH_ALIAS="<non-prod-alias>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match the selected non-production row
```

## Steps

### 0. Set first-deploy-safe runtime drivers

Some CodeCanyon vendors ship `.env` defaults like `CACHE_STORE=database`, `SESSION_DRIVER=database`, or `QUEUE_CONNECTION=database`. That is valid **after** the installer creates `cache`, `sessions`, and `jobs` tables. It is unsafe on the first deploy because Deployer runs cache/artisan checks before the installer builds those tables.

<Steps>

1. **Force file/sync drivers in the selected server `.env` before the first deploy.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/shared && \
     cp .env .env.before-first-deploy-drivers.$(date +%Y%m%d%H%M%S) && \
     grep -q '^CACHE_STORE=' .env && sed -i 's/^CACHE_STORE=.*/CACHE_STORE=file/' .env || printf '\nCACHE_STORE=file\n' >> .env; \
     grep -q '^CACHE_DRIVER=' .env && sed -i 's/^CACHE_DRIVER=.*/CACHE_DRIVER=file/' .env || printf '\nCACHE_DRIVER=file\n' >> .env; \
     grep -q '^SESSION_DRIVER=' .env && sed -i 's/^SESSION_DRIVER=.*/SESSION_DRIVER=file/' .env || printf '\nSESSION_DRIVER=file\n' >> .env; \
     grep -q '^QUEUE_CONNECTION=' .env && sed -i 's/^QUEUE_CONNECTION=.*/QUEUE_CONNECTION=sync/' .env || printf '\nQUEUE_CONNECTION=sync\n' >> .env; \
     grep -E '^(CACHE_STORE|CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env"
   # Expected: CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync
   ```

   - ✅ The first deploy cannot fail because cache/session/queue database tables do not exist yet.

</Steps>

:::note[After the installer]
Once the installer has created the schema, you may intentionally switch a project back to database/Redis drivers in a later phase. Do that as an explicit change with `migrate:status`, queue/scheduler verification, and a `Zaj-CUSTOMIZATIONS.md` note — not as a hidden first-deploy default.
:::

### 1. Dry-run, then deploy

Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.

<Steps>

1. **Preview, then run the atomic deploy.**

   ```bash
   dep deploy "$DEPLOY_TARGET" --plan    # final review of the task pipeline (see page 1)
   dep deploy "$DEPLOY_TARGET"           # atomic release; symlink flips only on success
   # Expected: "Successfully deployed!" — symlink flips only after the smoke test passes
   ```

   - ✅ `Successfully deployed!`; `current` now points at the new release.

</Steps>

The smoke test gates the symlink flip — a failed build never touches the live release:

```mermaid
flowchart LR
  P["--plan<br/>(preview)"] --> B["build release"]
  B --> S["smoke test"]
  S -->|pass| F["flip current ✅"]
  S -->|fail| K["abort — live release untouched"]
  style F fill:#0b3,stroke:#062,color:#fff
  style K fill:#a40,stroke:#600,color:#fff
```

First-deploy behavior (Release 1): migrations are **skipped automatically** — the web installer owns the initial schema — and `APP_KEY` is auto-generated if missing. Expect `Successfully deployed!`.

If the first-release smoke test returns an unfamiliar `500`, start with [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/): tail `laravel.log`, classify the first fragment, then fix the matching layer instead of redeploying blind.

| At this step | First response | Likely next move |
|---|---|---|
| `500` after symlink flip | Tail `storage/logs/laravel.log` | Use the 500 classification table |
| Empty Laravel log | Check `current/storage/logs/` and `shared/storage/logs/` | Confirm logging target or Sentry-only routing |

:::note[The first release skips migrations on purpose]
Letting Deployer's migrate hook run before the web installer would fight the wizard. Migrations via the deploy hook resume on subsequent releases. If the deploy stops on pending migrations, it prints `migrate --pretend` output — review it, then re-run with `dep deploy "$DEPLOY_TARGET" --allow-pending`.
:::

### 2. Confirm APP_KEY and clear caches

Confirm the health check generated `APP_KEY`, remove any stale install lock, then clear caches with the **versioned** PHP binary.

<Steps>

1. **Confirm `APP_KEY` is present.**

   ```bash
   ssh "$SSH_ALIAS" "grep APP_KEY $DEPLOY_PATH/shared/.env | head -1"
   # Expected: APP_KEY=base64:... (44+ chars)
   ```

   - ✅ `APP_KEY=base64:...` is set with 44+ characters.

2. **Generate `APP_KEY` once if it's empty** (common after a failed first deploy where the health check never ran).

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && php artisan key:generate --force"
   # Expected: "Application key set successfully."
   ```

   - ✅ A key is set if one was missing.

3. **Remove any stale install lock, then clear caches with the versioned PHP binary.**

   ```bash
   ssh "$SSH_ALIAS" "rm -f $DEPLOY_PATH/shared/storage/installed 2>/dev/null"

   # Use the absolute versioned binary from deploy.php — NOT bare `php`.
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan optimize:clear"
   # Expected: each cache layer reports "cleared"
   ```

   - ✅ Stale lock removed; `optimize:clear` flushes every cache layer.

</Steps>

:::caution[Why `optimize:clear` and why the full PHP path]
`optimize:clear` flushes config, cache, compiled, events, routes, views, and blade-icons in one idempotent call. Running only `config:clear && cache:clear` leaves stale compiled views and event caches — the exact cause of "I deployed new blade files but staging shows old content." And bare `php` in an SSH session resolves to the shell default, often older than `composer.json` requires; when the versions disagree, `artisan` crashes on autoloader constraints before your command runs. This is the single most common "staging cache won't clear" failure.
:::

### 3. Verify the Deployer directory structure

Confirm Deployer laid out the atomic release tree as expected.

<Steps>

1. **List the deploy tree.**

   ```bash
   ssh "$SSH_ALIAS" "ls -la $DEPLOY_PATH/"
   # Expected: releases/, shared/, current -> releases/1, and .dep/
   ```

   - ✅ The tree shows `releases/`, `shared/`, `current -> releases/1`, and `.dep/`.

</Steps>

The expected shape:

```
deploy/
├── releases/
│   └── 1/                  ← current release
├── shared/
│   ├── .env                ← persistent environment
│   ├── storage/            ← persistent files (logs, uploads)
│   └── .user.ini           ← PHP settings
├── current -> releases/1   ← symlink to latest release
└── .dep/                   ← Deployer metadata
```

### 4. Verify the `.env` symlink (BLOCKER)

`shared_files` controls which files Deployer symlinks from `shared/` into each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently loading the wrong database, cache driver, or keys. This exact bug cost a 90-minute debugging session. The check below catches it in seconds.

<Steps>

1. **Confirm `current/.env` is a symlink into `shared/.env`, and that Laravel reads your values.**

   ```bash
   # 1. Must be a symbolic link
   ssh "$SSH_ALIAS" "stat -c '%F' $DEPLOY_PATH/current/.env"
   # expected: symbolic link   (regular file = shared_files broken; missing = app will crash)

   # 2. Target must resolve into shared/.env
   ssh "$SSH_ALIAS" "readlink -f $DEPLOY_PATH/current/.env"
   # expected: .../deploy/shared/.env

   # 3. Laravel must actually read your values (not the vendor fallback)
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan tinker --execute=\"
       echo 'cache.default  = '.config('cache.default').PHP_EOL;
       echo 'session.driver = '.config('session.driver').PHP_EOL;
       echo 'queue.default  = '.config('queue.default').PHP_EOL;
     \""
   # Expected: "symbolic link", a path ending in shared/.env, and YOUR cache/session/queue values
   ```

   - ✅ `current/.env` is a symbolic link resolving to `shared/.env`, and Laravel resolves your real cache/session/queue values.

</Steps>

:::danger[If `current/.env` is a regular file or missing — STOP]
A regular file means `shared_files` did not symlink it; missing means every request crashes with *"No application encryption key."* Fix `deploy.php` (`set('shared_files', [])` → `add('shared_files', [...])` so the recipe default `.env` is preserved), commit, and redeploy. Do not run the installer until `current/.env` resolves to `shared/.env`.
:::

If `cache.default` resolves to something other than what `shared/.env` sets, suspect a **variable-name mismatch** for your Laravel version:

| Laravel version | `config/cache.php` reads | `.env` must set |
|---|---|---|
| Laravel 11+ | `env('CACHE_STORE', …)` | `CACHE_STORE=file` |
| Laravel 10 and earlier | `env('CACHE_DRIVER', …)` | `CACHE_DRIVER=file` |

Setting `CACHE_STORE` in a Laravel 10 `.env` is silently ignored — the config reads `CACHE_DRIVER`, gets nothing, and falls through to the template's hardcoded default (often `redis`).

### 5. Verify seeded storage/default content survived shared storage

CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations. The dangerous case is `storage/app/public/*`: Deployer replaces release `storage/` with shared `storage/`, so vendor-shipped logos can disappear unless `shared:init_defaults` copies them into shared storage before `deploy:shared` runs.

<Steps>

1. **Confirm the Deployer defaults hook exists and runs before shared symlinks.**

   ```bash
   grep -n "task('shared:init_defaults'" deploy.php
   grep -n "before('deploy:shared', 'shared:init_defaults')" deploy.php
   # Expected: the task exists and runs before deploy:shared
   ```

   - ✅ The first deploy has a hook that can copy release defaults before `storage/` is shadowed.

2. **Discover seeded content dirs locally and confirm the deploy plan preserves them.**

   ```bash
   # Discover content dirs locally
   for dir in uploads public/uploads public/images public/avatars public/themes \
              storage/app/public public/media public/assets/images; do
     [ -d "$dir" ] && echo "  $dir — $(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ') files"
   done
   grep -A10 "shared_dirs" deploy.php | grep "'"
	   # Expected: storage/app/public is handled by shared:init_defaults; other content dirs appear in shared_dirs
   ```

	   - ✅ `storage/app/public` is seeded by `shared:init_defaults`; every other content directory with demo files is listed in `shared_dirs`.

3. **Verify at least one seeded storage media file exists in shared storage and serves over HTTP.**

   ```bash
   SEEDED_MEDIA=$(find storage/app/public -type f 2>/dev/null | sed 's#^storage/app/public/##' | head -1)
   test -n "$SEEDED_MEDIA" || echo "No local storage/app/public seed files found — skip media URL proof"

   if [ -n "$SEEDED_MEDIA" ]; then
     ssh "$SSH_ALIAS" "test -f '$DEPLOY_PATH/shared/storage/app/public/$SEEDED_MEDIA' && echo 'shared media present'"
     curl -s -o /dev/null -w "%{http_code}\n" "https://$DEPLOY_DOMAIN/storage/$SEEDED_MEDIA"
   fi
   # Expected: "shared media present" and HTTP 200 for the media URL
   ```

   - ✅ A vendor-seeded storage media file exists in shared storage and returns `200`.

</Steps>

Every content directory with demo files must be preserved by one of two paths: `storage/app/public` is copied into shared storage by `shared:init_defaults` before `deploy:shared`, and other durable content dirs should be listed in `shared_dirs`. If seeded storage media is missing after the first deploy, copy it from the local vendor snapshot into shared storage and re-run the URL proof:

```bash
rsync -az storage/app/public/ "$SSH_ALIAS:$DEPLOY_PATH/shared/storage/app/public/"
# Expected: seeded storage/app/public files copied into shared storage
```

### 5.5. Verify (and relink) the public asset symlinks

`public/storage` (and, for in-tree module apps, `public/packages`) are **per-environment symlinks** — they point at a path that only makes sense on the machine that created them. Two server-side traps:

- The vendor often ships `public/storage` **tracked in Git as an absolute symlink to a dead path** (`/var/www/...`, `/home/<other-user>/...`). On your server that target doesn't exist, so every `/storage/*` URL (logos, avatars, uploaded media) returns **403/404** until it's relinked.
- WorkDo-style apps reference in-tree module assets as `/packages/<vendor>/<Module>/...` URLs, but `public/packages` doesn't exist out of the box → all module images 404 and the landing page looks broken. (These per-env symlinks should already be **gitignored** from Phase 2 — see [Initialize the repository](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/) §2. If a tracked `public/storage` symlink still rode along in the release, the relink below replaces it.)

<Steps>

1. **Inspect the server symlinks, then recreate them with the versioned PHP binary.**

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   REL="$DEPLOY_PATH/current"

   # What does public/storage currently resolve to? (a dead /var/www/... target = the trap)
   ssh "$SSH_ALIAS" "readlink -f $REL/public/storage 2>/dev/null; \
     [ -e $REL/public/storage ] && echo '  target exists' || echo '  ❌ target MISSING — relink below'"

   # Recreate the storage symlink fresh (rm the stale/dead one first; storage:link won't overwrite)
   ssh "$SSH_ALIAS" "cd $REL && rm -f public/storage && $PHP_BIN artisan storage:link && \
     readlink -f public/storage"
   # Expected: public/storage → .../shared/storage/app/public (an existing path on THIS server)
   ```

   - ✅ `public/storage` resolves to a path that exists on the server (not a dead `/var/www/...`).

2. **If the app serves in-tree module assets (e.g. WorkDo `packages/`), add the `public/packages` link too.**

   ```bash
   ssh "$SSH_ALIAS" "cd $REL && [ -d packages ] && [ ! -e public/packages ] && \
     ln -s ../packages public/packages && echo '  ✅ public/packages linked' || echo '  (no packages/ dir, or already linked)'"
   # Expected: public/packages exists only when packages/ is shipped
   ```

   - ✅ `public/packages` exists when the app ships in-tree module assets; otherwise `test ! -d packages` proves `N/A — no in-tree package assets on this release`.

</Steps>

:::caution[`public/packages` exposes `.php` source — restrict it before production]
A blanket `ln -s ../packages public/packages` maps the **entire** module tree under the webroot, including `.php` source. That's acceptable on staging, but for production restrict `/packages` to asset extensions (an `.htaccess`/nginx rule allowing only `css|js|png|jpg|svg|woff*`) — or publish module assets into `public/` instead of symlinking. Note the decision in `Zaj-CUSTOMIZATIONS.md`.
:::

:::note[These are per-env — recreate, never commit]
`public/storage` and `public/packages` are recreated on **every** environment (local in Phase 3, here on staging, again on production in Phase 12). They must stay **gitignored** — a committed symlink carries one machine's dead path to all the others. Deployer's `shared_dirs` persists the underlying `shared/storage/` across releases; the symlink itself is cheap to recreate.
:::

### 6. Loosen permissions for the installer

The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

<Steps>

1. **Loosen storage and cache permissions for the installer.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     chmod -R 777 storage bootstrap/cache resources/lang uploads 2>/dev/null; \
     chmod -R 777 $DEPLOY_PATH/shared/storage 2>/dev/null && echo 'Permissions set to 777'"
   # Expected: "Permissions set to 777"
   ```

   - ✅ `Permissions set to 777` — the installer's writable paths are ready.

</Steps>

:::danger[777 is temporary — page 4 re-hardens it]
World-writable app + storage is a serious vulnerability. The installer needs it; the re-harden step on the next page is **not optional**.
:::

## Background

### Troubleshooting — first-release failures

- **`Connection refused 127.0.0.1:6379` on the first artisan task** — the release is loading `.env` from a fallback, not `shared/.env`. This is the symlink BLOCKER above. Switch `set('shared_files', …)` → `add('shared_files', …)`, or untrack a committed `.env` (`git rm --cached .env`), then redeploy.
- **`SQLSTATE[42S02]: Table '…cache' doesn't exist` before the installer** — the vendor defaults cache/session/queue to database drivers before the installer creates those tables. Re-run section 0 and set `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync`, then redeploy.
- **`Too many levels of symbolic links` during `deploy:shared`** — a file is listed in `shared_files` *and* lives inside a `shared_dirs` directory (e.g. `storage/.ignore_locales` with `shared_dirs: ['storage']`). A file may be in one or the other, never both. Remove the `shared_files` entry — `shared_dirs` already persists it. Fails before the symlink switch, so no downtime.
- **`Class not found` (Faker / Debugbar / Telescope)** — production code references a dev-only package excluded by `composer install --no-dev`. Guard with `class_exists()` or move the logic into seeders; add to prod deps only as a last resort.
- **`Vite manifest not found`** — `public/build/` is gitignored and wasn't deployed. For the build-locally strategy, un-ignore it: `git add -f public/build/ && git commit && dep deploy "$DEPLOY_TARGET"`.
- **All `/storage/*` (or `/packages/*`) URLs 403/404 — images/avatars/uploads broken** — the server's `public/storage` points at a dead absolute path (often a vendor-shipped symlink to `/var/www/...`), or `public/packages` was never created. Relink per §5.5: `rm -f public/storage && $PHP_BIN artisan storage:link`, and `ln -s ../packages public/packages` for in-tree module apps. Both are per-env and must stay gitignored.
- **Livewire "published assets are out of date"** — the Livewire package and the published assets in `public/vendor/livewire/` disagree, so `wire:model` silently fails and component state is lost on refresh. One-off fix: resolve `$PHP_BIN` from `deploy.php` (same as §3), then `ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan livewire:publish --assets"`, then purge the CDN cache. Prevention: the deploy template runs a `livewire:publish_assets` task after `vendor:restore` on every release — copy it in if your `deploy.php` predates it.
- **`your php version does not satisfy that requirement` at `deploy:vendors`** — web SAPI PHP is below `composer.json`. Fixes belong on page 1's PHP triple-check: upgrade in hPanel, update `bin/php`, redeploy. Fails before the symlink switch.
- **Emergency rollback** — `dep rollback "$DEPLOY_TARGET"` (changes the symlink to the previous release; no files deleted).

## Checklist

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

- [ ] **🤖 First-deploy drivers safe** — `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync` before installer tables exist.
- [ ] **🤖 Release deployed** — `dep deploy "$DEPLOY_TARGET"` completed for the selected non-production target; `current` symlinks to the new release.
- [ ] **🤖 Key + caches** — `APP_KEY` present (44+ chars); install lock removed; caches cleared with the versioned PHP.
- [ ] **🤖 Deployer tree correct** — `current`, `releases/`, `shared/`, `.dep/`.
- [ ] **🤖 `.env` symlink resolves** — `current/.env` is a symlink into `shared/.env`; Laravel resolves your cache/session/queue values.
- [ ] **🤖 Seeded storage content present** — vendor storage defaults copied to shared storage; at least one expected media URL returns `200`.
- [ ] **🤖 Public symlinks relinked** — `public/storage` resolves to an existing server path (not a dead `/var/www/...`); `public/packages` linked if the app ships in-tree module assets; both stay gitignored.
- [ ] **🤖 Installer permissions set** — 777 for the installer (re-hardened on page 4).

:::next[Next step]
[Installer + smoke path](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/04-installer-smoke/)
:::

# 3 · First release

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/03-first-release/

## TL;DR

**Objective** — ship the app's first atomic release and prove it booted correctly: force first-deploy-safe cache/session/queue drivers when the vendor defaults to database-backed drivers, confirm `APP_KEY`, clear caches with the versioned PHP binary, verify the Deployer tree and the `.env` symlink (a 5-second check that prevents a 90-minute outage), confirm seeded storage assets survived `shared_dirs`, then loosen permissions for the installer.

**Steps at a glance:**
0. **Set first-deploy-safe runtime drivers** — Some vendors default cache/session/queue to database tables the
   installer has not created yet. Use file/sync drivers until the installer completes.
1. **Dry-run, then deploy** — Preview the pipeline one last time, then run the atomic release. The symlink flips
   only on a passing smoke test.
2. **Confirm APP_KEY and clear caches** — Confirm the health check generated `APP_KEY`, remove any stale install
   lock, then clear caches with the versioned PHP binary.
3. **Verify the Deployer directory structure** — Confirm Deployer laid out the atomic release tree as expected.
4. **Verify the `.env` symlink** — `shared_files` controls which files Deployer symlinks from `shared/` into
   each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's
   default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently
   loading the wrong.
5. **Verify demo/default content deployed** — CodeCanyon apps ship demo content (images, avatars, themes, sample
   data) in app-specific locations.
6. **Loosen permissions for the installer** — The web installer requires writable paths. This is a deliberate,
   temporary loosening — it gets hardened on page 4.

:::note[User part + done-when]
**👤 User part** — almost none: this step is entirely SSH/CLI-runnable. A person only needs to read the `.env`-symlink BLOCKER outcome to decide whether to STOP.

**Done when** first-deploy-safe drivers are active, `dep deploy "$DEPLOY_TARGET"` succeeds for the selected non-production row in `Zaj-PROJECT.md`, `current` symlinks to the new release, `APP_KEY` is present, `current/.env` resolves to `shared/.env`, seeded storage/media content is present in shared storage, and permissions are loosened for the installer. &nbsp;·&nbsp; **⏱ ~30–45 min** &nbsp;·&nbsp; 🤖 agent-runnable.
:::

## Background

The payoff of Phase 4 — the app's first atomic release. Deployer flips the `current` symlink **only** after the smoke test passes, so a failed build never touches the live release.

:::note[First live deploy proof lives here]
Phase 4 authored the Deployer and GitHub Actions artifacts. This page is the first [RUN-LIVE] deploy proof: run the release directly with Deployer, or trigger the CI deploy workflow for the selected non-production target and verify it reaches the same symlink/current checks below. Do not backfill that proof into Phase 4.
:::

Reuse the environment variables from page 1, or reload them from `Zaj-PROJECT.md` before running commands:

```bash
ENV_KEY="staging-primary"        # example; use the selected Zaj-PROJECT.md row
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer target from that row
SSH_ALIAS="<non-prod-alias>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match the selected non-production row
```

## Steps

### 0. Set first-deploy-safe runtime drivers

Some CodeCanyon vendors ship `.env` defaults like `CACHE_STORE=database`, `SESSION_DRIVER=database`, or `QUEUE_CONNECTION=database`. That is valid **after** the installer creates `cache`, `sessions`, and `jobs` tables. It is unsafe on the first deploy because Deployer runs cache/artisan checks before the installer builds those tables.

<Steps>

1. **Force file/sync drivers in the selected server `.env` before the first deploy.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/shared && \
     cp .env .env.before-first-deploy-drivers.$(date +%Y%m%d%H%M%S) && \
     grep -q '^CACHE_STORE=' .env && sed -i 's/^CACHE_STORE=.*/CACHE_STORE=file/' .env || printf '\nCACHE_STORE=file\n' >> .env; \
     grep -q '^CACHE_DRIVER=' .env && sed -i 's/^CACHE_DRIVER=.*/CACHE_DRIVER=file/' .env || printf '\nCACHE_DRIVER=file\n' >> .env; \
     grep -q '^SESSION_DRIVER=' .env && sed -i 's/^SESSION_DRIVER=.*/SESSION_DRIVER=file/' .env || printf '\nSESSION_DRIVER=file\n' >> .env; \
     grep -q '^QUEUE_CONNECTION=' .env && sed -i 's/^QUEUE_CONNECTION=.*/QUEUE_CONNECTION=sync/' .env || printf '\nQUEUE_CONNECTION=sync\n' >> .env; \
     grep -E '^(CACHE_STORE|CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env"
   # Expected: CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync
   ```

   - ✅ The first deploy cannot fail because cache/session/queue database tables do not exist yet.

</Steps>

:::note[After the installer]
Once the installer has created the schema, you may intentionally switch a project back to database/Redis drivers in a later phase. Do that as an explicit change with `migrate:status`, queue/scheduler verification, and a `Zaj-CUSTOMIZATIONS.md` note — not as a hidden first-deploy default.
:::

### 1. Dry-run, then deploy

Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.

<Steps>

1. **Preview, then run the atomic deploy.**

   ```bash
   dep deploy "$DEPLOY_TARGET" --plan    # final review of the task pipeline (see page 1)
   dep deploy "$DEPLOY_TARGET"           # atomic release; symlink flips only on success
   # Expected: "Successfully deployed!" — symlink flips only after the smoke test passes
   ```

   - ✅ `Successfully deployed!`; `current` now points at the new release.

</Steps>

The smoke test gates the symlink flip — a failed build never touches the live release:

```mermaid
flowchart LR
  P["--plan<br/>(preview)"] --> B["build release"]
  B --> S["smoke test"]
  S -->|pass| F["flip current ✅"]
  S -->|fail| K["abort — live release untouched"]
  style F fill:#0b3,stroke:#062,color:#fff
  style K fill:#a40,stroke:#600,color:#fff
```

First-deploy behavior (Release 1): migrations are **skipped automatically** — the web installer owns the initial schema — and `APP_KEY` is auto-generated if missing. Expect `Successfully deployed!`.

If the first-release smoke test returns an unfamiliar `500`, start with [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/): tail `laravel.log`, classify the first fragment, then fix the matching layer instead of redeploying blind.

| At this step | First response | Likely next move |
|---|---|---|
| `500` after symlink flip | Tail `storage/logs/laravel.log` | Use the 500 classification table |
| Empty Laravel log | Check `current/storage/logs/` and `shared/storage/logs/` | Confirm logging target or Sentry-only routing |

:::note[The first release skips migrations on purpose]
Letting Deployer's migrate hook run before the web installer would fight the wizard. Migrations via the deploy hook resume on subsequent releases. If the deploy stops on pending migrations, it prints `migrate --pretend` output — review it, then re-run with `dep deploy "$DEPLOY_TARGET" --allow-pending`.
:::

### 2. Confirm APP_KEY and clear caches

Confirm the health check generated `APP_KEY`, remove any stale install lock, then clear caches with the **versioned** PHP binary.

<Steps>

1. **Confirm `APP_KEY` is present.**

   ```bash
   ssh "$SSH_ALIAS" "grep APP_KEY $DEPLOY_PATH/shared/.env | head -1"
   # Expected: APP_KEY=base64:... (44+ chars)
   ```

   - ✅ `APP_KEY=base64:...` is set with 44+ characters.

2. **Generate `APP_KEY` once if it's empty** (common after a failed first deploy where the health check never ran).

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && php artisan key:generate --force"
   # Expected: "Application key set successfully."
   ```

   - ✅ A key is set if one was missing.

3. **Remove any stale install lock, then clear caches with the versioned PHP binary.**

   ```bash
   ssh "$SSH_ALIAS" "rm -f $DEPLOY_PATH/shared/storage/installed 2>/dev/null"

   # Use the absolute versioned binary from deploy.php — NOT bare `php`.
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan optimize:clear"
   # Expected: each cache layer reports "cleared"
   ```

   - ✅ Stale lock removed; `optimize:clear` flushes every cache layer.

</Steps>

:::caution[Why `optimize:clear` and why the full PHP path]
`optimize:clear` flushes config, cache, compiled, events, routes, views, and blade-icons in one idempotent call. Running only `config:clear && cache:clear` leaves stale compiled views and event caches — the exact cause of "I deployed new blade files but staging shows old content." And bare `php` in an SSH session resolves to the shell default, often older than `composer.json` requires; when the versions disagree, `artisan` crashes on autoloader constraints before your command runs. This is the single most common "staging cache won't clear" failure.
:::

### 3. Verify the Deployer directory structure

Confirm Deployer laid out the atomic release tree as expected.

<Steps>

1. **List the deploy tree.**

   ```bash
   ssh "$SSH_ALIAS" "ls -la $DEPLOY_PATH/"
   # Expected: releases/, shared/, current -> releases/1, and .dep/
   ```

   - ✅ The tree shows `releases/`, `shared/`, `current -> releases/1`, and `.dep/`.

</Steps>

The expected shape:

```
deploy/
├── releases/
│   └── 1/                  ← current release
├── shared/
│   ├── .env                ← persistent environment
│   ├── storage/            ← persistent files (logs, uploads)
│   └── .user.ini           ← PHP settings
├── current -> releases/1   ← symlink to latest release
└── .dep/                   ← Deployer metadata
```

### 4. Verify the `.env` symlink (BLOCKER)

`shared_files` controls which files Deployer symlinks from `shared/` into each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently loading the wrong database, cache driver, or keys. This exact bug cost a 90-minute debugging session. The check below catches it in seconds.

<Steps>

1. **Confirm `current/.env` is a symlink into `shared/.env`, and that Laravel reads your values.**

   ```bash
   # 1. Must be a symbolic link
   ssh "$SSH_ALIAS" "stat -c '%F' $DEPLOY_PATH/current/.env"
   # expected: symbolic link   (regular file = shared_files broken; missing = app will crash)

   # 2. Target must resolve into shared/.env
   ssh "$SSH_ALIAS" "readlink -f $DEPLOY_PATH/current/.env"
   # expected: .../deploy/shared/.env

   # 3. Laravel must actually read your values (not the vendor fallback)
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan tinker --execute=\"
       echo 'cache.default  = '.config('cache.default').PHP_EOL;
       echo 'session.driver = '.config('session.driver').PHP_EOL;
       echo 'queue.default  = '.config('queue.default').PHP_EOL;
     \""
   # Expected: "symbolic link", a path ending in shared/.env, and YOUR cache/session/queue values
   ```

   - ✅ `current/.env` is a symbolic link resolving to `shared/.env`, and Laravel resolves your real cache/session/queue values.

</Steps>

:::danger[If `current/.env` is a regular file or missing — STOP]
A regular file means `shared_files` did not symlink it; missing means every request crashes with *"No application encryption key."* Fix `deploy.php` (`set('shared_files', [])` → `add('shared_files', [...])` so the recipe default `.env` is preserved), commit, and redeploy. Do not run the installer until `current/.env` resolves to `shared/.env`.
:::

If `cache.default` resolves to something other than what `shared/.env` sets, suspect a **variable-name mismatch** for your Laravel version:

| Laravel version | `config/cache.php` reads | `.env` must set |
|---|---|---|
| Laravel 11+ | `env('CACHE_STORE', …)` | `CACHE_STORE=file` |
| Laravel 10 and earlier | `env('CACHE_DRIVER', …)` | `CACHE_DRIVER=file` |

Setting `CACHE_STORE` in a Laravel 10 `.env` is silently ignored — the config reads `CACHE_DRIVER`, gets nothing, and falls through to the template's hardcoded default (often `redis`).

### 5. Verify seeded storage/default content survived shared storage

CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations. The dangerous case is `storage/app/public/*`: Deployer replaces release `storage/` with shared `storage/`, so vendor-shipped logos can disappear unless `shared:init_defaults` copies them into shared storage before `deploy:shared` runs.

<Steps>

1. **Confirm the Deployer defaults hook exists and runs before shared symlinks.**

   ```bash
   grep -n "task('shared:init_defaults'" deploy.php
   grep -n "before('deploy:shared', 'shared:init_defaults')" deploy.php
   # Expected: the task exists and runs before deploy:shared
   ```

   - ✅ The first deploy has a hook that can copy release defaults before `storage/` is shadowed.

2. **Discover seeded content dirs locally and confirm the deploy plan preserves them.**

   ```bash
   # Discover content dirs locally
   for dir in uploads public/uploads public/images public/avatars public/themes \
              storage/app/public public/media public/assets/images; do
     [ -d "$dir" ] && echo "  $dir — $(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ') files"
   done
   grep -A10 "shared_dirs" deploy.php | grep "'"
	   # Expected: storage/app/public is handled by shared:init_defaults; other content dirs appear in shared_dirs
   ```

	   - ✅ `storage/app/public` is seeded by `shared:init_defaults`; every other content directory with demo files is listed in `shared_dirs`.

3. **Verify at least one seeded storage media file exists in shared storage and serves over HTTP.**

   ```bash
   SEEDED_MEDIA=$(find storage/app/public -type f 2>/dev/null | sed 's#^storage/app/public/##' | head -1)
   test -n "$SEEDED_MEDIA" || echo "No local storage/app/public seed files found — skip media URL proof"

   if [ -n "$SEEDED_MEDIA" ]; then
     ssh "$SSH_ALIAS" "test -f '$DEPLOY_PATH/shared/storage/app/public/$SEEDED_MEDIA' && echo 'shared media present'"
     curl -s -o /dev/null -w "%{http_code}\n" "https://$DEPLOY_DOMAIN/storage/$SEEDED_MEDIA"
   fi
   # Expected: "shared media present" and HTTP 200 for the media URL
   ```

   - ✅ A vendor-seeded storage media file exists in shared storage and returns `200`.

</Steps>

Every content directory with demo files must be preserved by one of two paths: `storage/app/public` is copied into shared storage by `shared:init_defaults` before `deploy:shared`, and other durable content dirs should be listed in `shared_dirs`. If seeded storage media is missing after the first deploy, copy it from the local vendor snapshot into shared storage and re-run the URL proof:

```bash
rsync -az storage/app/public/ "$SSH_ALIAS:$DEPLOY_PATH/shared/storage/app/public/"
# Expected: seeded storage/app/public files copied into shared storage
```

### 5.5. Verify (and relink) the public asset symlinks

`public/storage` (and, for in-tree module apps, `public/packages`) are **per-environment symlinks** — they point at a path that only makes sense on the machine that created them. Two server-side traps:

- The vendor often ships `public/storage` **tracked in Git as an absolute symlink to a dead path** (`/var/www/...`, `/home/<other-user>/...`). On your server that target doesn't exist, so every `/storage/*` URL (logos, avatars, uploaded media) returns **403/404** until it's relinked.
- WorkDo-style apps reference in-tree module assets as `/packages/<vendor>/<Module>/...` URLs, but `public/packages` doesn't exist out of the box → all module images 404 and the landing page looks broken. (These per-env symlinks should already be **gitignored** from Phase 2 — see [Initialize the repository](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/) §2. If a tracked `public/storage` symlink still rode along in the release, the relink below replaces it.)

<Steps>

1. **Inspect the server symlinks, then recreate them with the versioned PHP binary.**

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   REL="$DEPLOY_PATH/current"

   # What does public/storage currently resolve to? (a dead /var/www/... target = the trap)
   ssh "$SSH_ALIAS" "readlink -f $REL/public/storage 2>/dev/null; \
     [ -e $REL/public/storage ] && echo '  target exists' || echo '  ❌ target MISSING — relink below'"

   # Recreate the storage symlink fresh (rm the stale/dead one first; storage:link won't overwrite)
   ssh "$SSH_ALIAS" "cd $REL && rm -f public/storage && $PHP_BIN artisan storage:link && \
     readlink -f public/storage"
   # Expected: public/storage → .../shared/storage/app/public (an existing path on THIS server)
   ```

   - ✅ `public/storage` resolves to a path that exists on the server (not a dead `/var/www/...`).

2. **If the app serves in-tree module assets (e.g. WorkDo `packages/`), add the `public/packages` link too.**

   ```bash
   ssh "$SSH_ALIAS" "cd $REL && [ -d packages ] && [ ! -e public/packages ] && \
     ln -s ../packages public/packages && echo '  ✅ public/packages linked' || echo '  (no packages/ dir, or already linked)'"
   # Expected: public/packages exists only when packages/ is shipped
   ```

   - ✅ `public/packages` exists when the app ships in-tree module assets; otherwise `test ! -d packages` proves `N/A — no in-tree package assets on this release`.

</Steps>

:::caution[`public/packages` exposes `.php` source — restrict it before production]
A blanket `ln -s ../packages public/packages` maps the **entire** module tree under the webroot, including `.php` source. That's acceptable on staging, but for production restrict `/packages` to asset extensions (an `.htaccess`/nginx rule allowing only `css|js|png|jpg|svg|woff*`) — or publish module assets into `public/` instead of symlinking. Note the decision in `Zaj-CUSTOMIZATIONS.md`.
:::

:::note[These are per-env — recreate, never commit]
`public/storage` and `public/packages` are recreated on **every** environment (local in Phase 3, here on staging, again on production in Phase 12). They must stay **gitignored** — a committed symlink carries one machine's dead path to all the others. Deployer's `shared_dirs` persists the underlying `shared/storage/` across releases; the symlink itself is cheap to recreate.
:::

### 6. Loosen permissions for the installer

The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

<Steps>

1. **Loosen storage and cache permissions for the installer.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     chmod -R 777 storage bootstrap/cache resources/lang uploads 2>/dev/null; \
     chmod -R 777 $DEPLOY_PATH/shared/storage 2>/dev/null && echo 'Permissions set to 777'"
   # Expected: "Permissions set to 777"
   ```

   - ✅ `Permissions set to 777` — the installer's writable paths are ready.

</Steps>

:::danger[777 is temporary — page 4 re-hardens it]
World-writable app + storage is a serious vulnerability. The installer needs it; the re-harden step on the next page is **not optional**.
:::

## Background

### Troubleshooting — first-release failures

- **`Connection refused 127.0.0.1:6379` on the first artisan task** — the release is loading `.env` from a fallback, not `shared/.env`. This is the symlink BLOCKER above. Switch `set('shared_files', …)` → `add('shared_files', …)`, or untrack a committed `.env` (`git rm --cached .env`), then redeploy.
- **`SQLSTATE[42S02]: Table '…cache' doesn't exist` before the installer** — the vendor defaults cache/session/queue to database drivers before the installer creates those tables. Re-run section 0 and set `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync`, then redeploy.
- **`Too many levels of symbolic links` during `deploy:shared`** — a file is listed in `shared_files` *and* lives inside a `shared_dirs` directory (e.g. `storage/.ignore_locales` with `shared_dirs: ['storage']`). A file may be in one or the other, never both. Remove the `shared_files` entry — `shared_dirs` already persists it. Fails before the symlink switch, so no downtime.
- **`Class not found` (Faker / Debugbar / Telescope)** — production code references a dev-only package excluded by `composer install --no-dev`. Guard with `class_exists()` or move the logic into seeders; add to prod deps only as a last resort.
- **`Vite manifest not found`** — `public/build/` is gitignored and wasn't deployed. For the build-locally strategy, un-ignore it: `git add -f public/build/ && git commit && dep deploy "$DEPLOY_TARGET"`.
- **All `/storage/*` (or `/packages/*`) URLs 403/404 — images/avatars/uploads broken** — the server's `public/storage` points at a dead absolute path (often a vendor-shipped symlink to `/var/www/...`), or `public/packages` was never created. Relink per §5.5: `rm -f public/storage && $PHP_BIN artisan storage:link`, and `ln -s ../packages public/packages` for in-tree module apps. Both are per-env and must stay gitignored.
- **Livewire "published assets are out of date"** — the Livewire package and the published assets in `public/vendor/livewire/` disagree, so `wire:model` silently fails and component state is lost on refresh. One-off fix: resolve `$PHP_BIN` from `deploy.php` (same as §3), then `ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan livewire:publish --assets"`, then purge the CDN cache. Prevention: the deploy template runs a `livewire:publish_assets` task after `vendor:restore` on every release — copy it in if your `deploy.php` predates it.
- **`your php version does not satisfy that requirement` at `deploy:vendors`** — web SAPI PHP is below `composer.json`. Fixes belong on page 1's PHP triple-check: upgrade in hPanel, update `bin/php`, redeploy. Fails before the symlink switch.
- **Emergency rollback** — `dep rollback "$DEPLOY_TARGET"` (changes the symlink to the previous release; no files deleted).

## Checklist

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

- [ ] **🤖 First-deploy drivers safe** — `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync` before installer tables exist.
- [ ] **🤖 Release deployed** — `dep deploy "$DEPLOY_TARGET"` completed for the selected non-production target; `current` symlinks to the new release.
- [ ] **🤖 Key + caches** — `APP_KEY` present (44+ chars); install lock removed; caches cleared with the versioned PHP.
- [ ] **🤖 Deployer tree correct** — `current`, `releases/`, `shared/`, `.dep/`.
- [ ] **🤖 `.env` symlink resolves** — `current/.env` is a symlink into `shared/.env`; Laravel resolves your cache/session/queue values.
- [ ] **🤖 Seeded storage content present** — vendor storage defaults copied to shared storage; at least one expected media URL returns `200`.
- [ ] **🤖 Public symlinks relinked** — `public/storage` resolves to an existing server path (not a dead `/var/www/...`); `public/packages` linked if the app ships in-tree module assets; both stay gitignored.
- [ ] **🤖 Installer permissions set** — 777 for the installer (re-hardened on page 4).

:::next[Next step]
[Installer + smoke path](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/04-installer-smoke/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — ship the app’s first atomic release and prove it booted correctly: force first-deploy-safe cache/session/queue drivers when the vendor defaults to database-backed drivers, confirm APP_KEY, clear caches with the versioned PHP binary, verify the Deployer tree and the .env symlink (a 5-second check that prevents a 90-minute outage), confirm seeded storage assets survived shared_dirs, then loosen permissions for the installer.

Steps at a glance: 0. Set first-deploy-safe runtime drivers — Some vendors default cache/session/queue to database tables the installer has not created yet. Use file/sync drivers until the installer completes.

Dry-run, then deploy — Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.
Confirm APP_KEY and clear caches — Confirm the health check generated APP_KEY, remove any stale install lock, then clear caches with the versioned PHP binary.
Verify the Deployer directory structure — Confirm Deployer laid out the atomic release tree as expected.
Verify the .env symlink — shared_files controls which files Deployer symlinks from shared/ into each release. If someone used set('shared_files', []) instead of add('shared_files', [...]), the recipe’s default ['.env'] is wiped — and every release boots from .env.example or a stale vendor .env, silently loading the wrong.
Verify demo/default content deployed — CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations.
Loosen permissions for the installer — The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

Background

The payoff of Phase 4 — the app’s first atomic release. Deployer flips the current symlink only after the smoke test passes, so a failed build never touches the live release.

Reuse the environment variables from page 1, or reload them from Zaj-PROJECT.md before running commands:

ENV_KEY="staging-primary"        # example; use the selected Zaj-PROJECT.md row
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer target from that row
SSH_ALIAS="<non-prod-alias>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match the selected non-production row

Steps

0. Set first-deploy-safe runtime drivers

Some CodeCanyon vendors ship .env defaults like CACHE_STORE=database, SESSION_DRIVER=database, or QUEUE_CONNECTION=database. That is valid after the installer creates cache, sessions, and jobs tables. It is unsafe on the first deploy because Deployer runs cache/artisan checks before the installer builds those tables.

Force file/sync drivers in the selected server .env before the first deploy.

ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/shared && \
  cp .env .env.before-first-deploy-drivers.$(date +%Y%m%d%H%M%S) && \
  grep -q '^CACHE_STORE=' .env && sed -i 's/^CACHE_STORE=.*/CACHE_STORE=file/' .env || printf '\nCACHE_STORE=file\n' >> .env; \
  grep -q '^CACHE_DRIVER=' .env && sed -i 's/^CACHE_DRIVER=.*/CACHE_DRIVER=file/' .env || printf '\nCACHE_DRIVER=file\n' >> .env; \
  grep -q '^SESSION_DRIVER=' .env && sed -i 's/^SESSION_DRIVER=.*/SESSION_DRIVER=file/' .env || printf '\nSESSION_DRIVER=file\n' >> .env; \
  grep -q '^QUEUE_CONNECTION=' .env && sed -i 's/^QUEUE_CONNECTION=.*/QUEUE_CONNECTION=sync/' .env || printf '\nQUEUE_CONNECTION=sync\n' >> .env; \
  grep -E '^(CACHE_STORE|CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env"
# Expected: CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync

✅ The first deploy cannot fail because cache/session/queue database tables do not exist yet.

1. Dry-run, then deploy

Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.

Preview, then run the atomic deploy.

dep deploy "$DEPLOY_TARGET" --plan    # final review of the task pipeline (see page 1)
dep deploy "$DEPLOY_TARGET"           # atomic release; symlink flips only on success
# Expected: "Successfully deployed!" — symlink flips only after the smoke test passes

✅ Successfully deployed!; current now points at the new release.

The smoke test gates the symlink flip — a failed build never touches the live release:

flowchart LR
  P["--plan<br/>(preview)"] --> B["build release"]
  B --> S["smoke test"]
  S -->|pass| F["flip current ✅"]
  S -->|fail| K["abort — live release untouched"]
  style F fill:#0b3,stroke:#062,color:#fff
  style K fill:#a40,stroke:#600,color:#fff

First-deploy behavior (Release 1): migrations are skipped automatically — the web installer owns the initial schema — and APP_KEY is auto-generated if missing. Expect Successfully deployed!.

If the first-release smoke test returns an unfamiliar 500, start with HTTP error triage: tail laravel.log, classify the first fragment, then fix the matching layer instead of redeploying blind.

At this step	First response	Likely next move
`500` after symlink flip	Tail `storage/logs/laravel.log`	Use the 500 classification table
Empty Laravel log	Check `current/storage/logs/` and `shared/storage/logs/`	Confirm logging target or Sentry-only routing

2. Confirm APP_KEY and clear caches

Confirm the health check generated APP_KEY, remove any stale install lock, then clear caches with the versioned PHP binary.

Confirm APP_KEY is present.

ssh "$SSH_ALIAS" "grep APP_KEY $DEPLOY_PATH/shared/.env | head -1"
# Expected: APP_KEY=base64:... (44+ chars)

✅ APP_KEY=base64:... is set with 44+ characters.

Generate APP_KEY once if it’s empty (common after a failed first deploy where the health check never ran).
Terminal window
```
ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && php artisan key:generate --force"
# Expected: "Application key set successfully."
```
- ✅ A key is set if one was missing.

Remove any stale install lock, then clear caches with the versioned PHP binary.

ssh "$SSH_ALIAS" "rm -f $DEPLOY_PATH/shared/storage/installed 2>/dev/null"

# Use the absolute versioned binary from deploy.php — NOT bare `php`.
PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
PHP_BIN="${PHP_BIN:-php}"
ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
  $PHP_BIN artisan optimize:clear"
# Expected: each cache layer reports "cleared"

✅ Stale lock removed; optimize:clear flushes every cache layer.

3. Verify the Deployer directory structure

Confirm Deployer laid out the atomic release tree as expected.

List the deploy tree.

ssh "$SSH_ALIAS" "ls -la $DEPLOY_PATH/"
# Expected: releases/, shared/, current -> releases/1, and .dep/

✅ The tree shows releases/, shared/, current -> releases/1, and .dep/.

The expected shape:

deploy/
├── releases/
│   └── 1/                  ← current release
├── shared/
│   ├── .env                ← persistent environment
│   ├── storage/            ← persistent files (logs, uploads)
│   └── .user.ini           ← PHP settings
├── current -> releases/1   ← symlink to latest release
└── .dep/                   ← Deployer metadata

4. Verify the `.env` symlink (BLOCKER)

shared_files controls which files Deployer symlinks from shared/ into each release. If someone used set('shared_files', []) instead of add('shared_files', [...]), the recipe’s default ['.env'] is wiped — and every release boots from .env.example or a stale vendor .env, silently loading the wrong database, cache driver, or keys. This exact bug cost a 90-minute debugging session. The check below catches it in seconds.

Confirm current/.env is a symlink into shared/.env, and that Laravel reads your values.

# 1. Must be a symbolic link
ssh "$SSH_ALIAS" "stat -c '%F' $DEPLOY_PATH/current/.env"
# expected: symbolic link   (regular file = shared_files broken; missing = app will crash)

# 2. Target must resolve into shared/.env
ssh "$SSH_ALIAS" "readlink -f $DEPLOY_PATH/current/.env"
# expected: .../deploy/shared/.env

# 3. Laravel must actually read your values (not the vendor fallback)
PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
PHP_BIN="${PHP_BIN:-php}"
ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
  $PHP_BIN artisan tinker --execute=\"
    echo 'cache.default  = '.config('cache.default').PHP_EOL;
    echo 'session.driver = '.config('session.driver').PHP_EOL;
    echo 'queue.default  = '.config('queue.default').PHP_EOL;
  \""
# Expected: "symbolic link", a path ending in shared/.env, and YOUR cache/session/queue values

✅ current/.env is a symbolic link resolving to shared/.env, and Laravel resolves your real cache/session/queue values.

If cache.default resolves to something other than what shared/.env sets, suspect a variable-name mismatch for your Laravel version:

Laravel version	`config/cache.php` reads	`.env` must set
Laravel 11+	`env('CACHE_STORE', …)`	`CACHE_STORE=file`
Laravel 10 and earlier	`env('CACHE_DRIVER', …)`	`CACHE_DRIVER=file`

Setting CACHE_STORE in a Laravel 10 .env is silently ignored — the config reads CACHE_DRIVER, gets nothing, and falls through to the template’s hardcoded default (often redis).

5. Verify seeded storage/default content survived shared storage

CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations. The dangerous case is storage/app/public/*: Deployer replaces release storage/ with shared storage/, so vendor-shipped logos can disappear unless shared:init_defaults copies them into shared storage before deploy:shared runs.

Confirm the Deployer defaults hook exists and runs before shared symlinks.

grep -n "task('shared:init_defaults'" deploy.php
grep -n "before('deploy:shared', 'shared:init_defaults')" deploy.php
# Expected: the task exists and runs before deploy:shared

✅ The first deploy has a hook that can copy release defaults before storage/ is shadowed.

Discover seeded content dirs locally and confirm the deploy plan preserves them.

# Discover content dirs locally
for dir in uploads public/uploads public/images public/avatars public/themes \
           storage/app/public public/media public/assets/images; do
  [ -d "$dir" ] && echo "  $dir — $(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ') files"
done
grep -A10 "shared_dirs" deploy.php | grep "'"
    # Expected: storage/app/public is handled by shared:init_defaults; other content dirs appear in shared_dirs

✅ storage/app/public is seeded by shared:init_defaults; every other content directory with demo files is listed in shared_dirs.

Verify at least one seeded storage media file exists in shared storage and serves over HTTP.

SEEDED_MEDIA=$(find storage/app/public -type f 2>/dev/null | sed 's#^storage/app/public/##' | head -1)
test -n "$SEEDED_MEDIA" || echo "No local storage/app/public seed files found — skip media URL proof"

if [ -n "$SEEDED_MEDIA" ]; then
  ssh "$SSH_ALIAS" "test -f '$DEPLOY_PATH/shared/storage/app/public/$SEEDED_MEDIA' && echo 'shared media present'"
  curl -s -o /dev/null -w "%{http_code}\n" "https://$DEPLOY_DOMAIN/storage/$SEEDED_MEDIA"
fi
# Expected: "shared media present" and HTTP 200 for the media URL

✅ A vendor-seeded storage media file exists in shared storage and returns 200.

Every content directory with demo files must be preserved by one of two paths: storage/app/public is copied into shared storage by shared:init_defaults before deploy:shared, and other durable content dirs should be listed in shared_dirs. If seeded storage media is missing after the first deploy, copy it from the local vendor snapshot into shared storage and re-run the URL proof:

rsync -az storage/app/public/ "$SSH_ALIAS:$DEPLOY_PATH/shared/storage/app/public/"
# Expected: seeded storage/app/public files copied into shared storage

5.5. Verify (and relink) the public asset symlinks

public/storage (and, for in-tree module apps, public/packages) are per-environment symlinks — they point at a path that only makes sense on the machine that created them. Two server-side traps:

The vendor often ships public/storage tracked in Git as an absolute symlink to a dead path (/var/www/..., /home/<other-user>/...). On your server that target doesn’t exist, so every /storage/* URL (logos, avatars, uploaded media) returns 403/404 until it’s relinked.
WorkDo-style apps reference in-tree module assets as /packages/<vendor>/<Module>/... URLs, but public/packages doesn’t exist out of the box → all module images 404 and the landing page looks broken. (These per-env symlinks should already be gitignored from Phase 2 — see Initialize the repository §2. If a tracked public/storage symlink still rode along in the release, the relink below replaces it.)

Inspect the server symlinks, then recreate them with the versioned PHP binary.

PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
PHP_BIN="${PHP_BIN:-php}"
REL="$DEPLOY_PATH/current"

# What does public/storage currently resolve to? (a dead /var/www/... target = the trap)
ssh "$SSH_ALIAS" "readlink -f $REL/public/storage 2>/dev/null; \
  [ -e $REL/public/storage ] && echo '  target exists' || echo '  ❌ target MISSING — relink below'"

# Recreate the storage symlink fresh (rm the stale/dead one first; storage:link won't overwrite)
ssh "$SSH_ALIAS" "cd $REL && rm -f public/storage && $PHP_BIN artisan storage:link && \
  readlink -f public/storage"
# Expected: public/storage → .../shared/storage/app/public (an existing path on THIS server)

✅ public/storage resolves to a path that exists on the server (not a dead /var/www/...).

If the app serves in-tree module assets (e.g. WorkDo packages/), add the public/packages link too.

ssh "$SSH_ALIAS" "cd $REL && [ -d packages ] && [ ! -e public/packages ] && \
  ln -s ../packages public/packages && echo '  ✅ public/packages linked' || echo '  (no packages/ dir, or already linked)'"
# Expected: public/packages exists only when packages/ is shipped

✅ public/packages exists when the app ships in-tree module assets; otherwise test ! -d packages proves N/A — no in-tree package assets on this release.

6. Loosen permissions for the installer

The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

Loosen storage and cache permissions for the installer.

ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
  chmod -R 777 storage bootstrap/cache resources/lang uploads 2>/dev/null; \
  chmod -R 777 $DEPLOY_PATH/shared/storage 2>/dev/null && echo 'Permissions set to 777'"
# Expected: "Permissions set to 777"

✅ Permissions set to 777 — the installer’s writable paths are ready.

Background

Troubleshooting — first-release failures

Connection refused 127.0.0.1:6379 on the first artisan task — the release is loading .env from a fallback, not shared/.env. This is the symlink BLOCKER above. Switch set('shared_files', …) → add('shared_files', …), or untrack a committed .env (git rm --cached .env), then redeploy.
SQLSTATE[42S02]: Table '…cache' doesn't exist before the installer — the vendor defaults cache/session/queue to database drivers before the installer creates those tables. Re-run section 0 and set CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync, then redeploy.
Too many levels of symbolic links during deploy:shared — a file is listed in shared_files and lives inside a shared_dirs directory (e.g. storage/.ignore_locales with shared_dirs: ['storage']). A file may be in one or the other, never both. Remove the shared_files entry — shared_dirs already persists it. Fails before the symlink switch, so no downtime.
Class not found (Faker / Debugbar / Telescope) — production code references a dev-only package excluded by composer install --no-dev. Guard with class_exists() or move the logic into seeders; add to prod deps only as a last resort.
Vite manifest not found — public/build/ is gitignored and wasn’t deployed. For the build-locally strategy, un-ignore it: git add -f public/build/ && git commit && dep deploy "$DEPLOY_TARGET".
All /storage/* (or /packages/*) URLs 403/404 — images/avatars/uploads broken — the server’s public/storage points at a dead absolute path (often a vendor-shipped symlink to /var/www/...), or public/packages was never created. Relink per §5.5: rm -f public/storage && $PHP_BIN artisan storage:link, and ln -s ../packages public/packages for in-tree module apps. Both are per-env and must stay gitignored.
Livewire “published assets are out of date” — the Livewire package and the published assets in public/vendor/livewire/ disagree, so wire:model silently fails and component state is lost on refresh. One-off fix: resolve $PHP_BIN from deploy.php (same as §3), then ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan livewire:publish --assets", then purge the CDN cache. Prevention: the deploy template runs a livewire:publish_assets task after vendor:restore on every release — copy it in if your deploy.php predates it.
your php version does not satisfy that requirement at deploy:vendors — web SAPI PHP is below composer.json. Fixes belong on page 1’s PHP triple-check: upgrade in hPanel, update bin/php, redeploy. Fails before the symlink switch.
Emergency rollback — dep rollback "$DEPLOY_TARGET" (changes the symlink to the previous release; no files deleted).

Checklist

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

🤖 First-deploy drivers safe — CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync before installer tables exist.
🤖 Release deployed — dep deploy "$DEPLOY_TARGET" completed for the selected non-production target; current symlinks to the new release.
🤖 Key + caches — APP_KEY present (44+ chars); install lock removed; caches cleared with the versioned PHP.
🤖 Deployer tree correct — current, releases/, shared/, .dep/.
🤖 .env symlink resolves — current/.env is a symlink into shared/.env; Laravel resolves your cache/session/queue values.
🤖 Seeded storage content present — vendor storage defaults copied to shared storage; at least one expected media URL returns 200.
🤖 Public symlinks relinked — public/storage resolves to an existing server path (not a dead /var/www/...); public/packages linked if the app ships in-tree module assets; both stay gitignored.
🤖 Installer permissions set — 777 for the installer (re-hardened on page 4).

Installer + smoke path

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 3 · First release
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/03-first-release/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 5
- part_number: 3 (legacy stepNumber frontmatter)
- legacy_step_number: 3
- est_time: ~30–45 min
- description: Run the atomic first deploy, confirm APP_KEY and clear caches with the versioned PHP binary, verify the Deployer directory tree and the .env symlink (a 5-second check that prevents a 90-minute outage), confirm demo content, then loosen permissions for the installer.
- tags: codecanyon, laravel, deployer, release

## Execution rules (binding)
- This is Part 3 of phase 5 (~30–45 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 3 · First release

## TL;DR

**Objective** — ship the app's first atomic release and prove it booted correctly: force first-deploy-safe cache/session/queue drivers when the vendor defaults to database-backed drivers, confirm `APP_KEY`, clear caches with the versioned PHP binary, verify the Deployer tree and the `.env` symlink (a 5-second check that prevents a 90-minute outage), confirm seeded storage assets survived `shared_dirs`, then loosen permissions for the installer.

**Steps at a glance:**
0. **Set first-deploy-safe runtime drivers** — Some vendors default cache/session/queue to database tables the
   installer has not created yet. Use file/sync drivers until the installer completes.
1. **Dry-run, then deploy** — Preview the pipeline one last time, then run the atomic release. The symlink flips
   only on a passing smoke test.
2. **Confirm APP_KEY and clear caches** — Confirm the health check generated `APP_KEY`, remove any stale install
   lock, then clear caches with the versioned PHP binary.
3. **Verify the Deployer directory structure** — Confirm Deployer laid out the atomic release tree as expected.
4. **Verify the `.env` symlink** — `shared_files` controls which files Deployer symlinks from `shared/` into
   each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's
   default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently
   loading the wrong.
5. **Verify demo/default content deployed** — CodeCanyon apps ship demo content (images, avatars, themes, sample
   data) in app-specific locations.
6. **Loosen permissions for the installer** — The web installer requires writable paths. This is a deliberate,
   temporary loosening — it gets hardened on page 4.

:::note[User part + done-when]
**👤 User part** — almost none: this step is entirely SSH/CLI-runnable. A person only needs to read the `.env`-symlink BLOCKER outcome to decide whether to STOP.

**Done when** first-deploy-safe drivers are active, `dep deploy "$DEPLOY_TARGET"` succeeds for the selected non-production row in `Zaj-PROJECT.md`, `current` symlinks to the new release, `APP_KEY` is present, `current/.env` resolves to `shared/.env`, seeded storage/media content is present in shared storage, and permissions are loosened for the installer. &nbsp;·&nbsp; **⏱ ~30–45 min** &nbsp;·&nbsp; 🤖 agent-runnable.
:::

## Background

The payoff of Phase 4 — the app's first atomic release. Deployer flips the `current` symlink **only** after the smoke test passes, so a failed build never touches the live release.

:::note[First live deploy proof lives here]
Phase 4 authored the Deployer and GitHub Actions artifacts. This page is the first [RUN-LIVE] deploy proof: run the release directly with Deployer, or trigger the CI deploy workflow for the selected non-production target and verify it reaches the same symlink/current checks below. Do not backfill that proof into Phase 4.
:::

Reuse the environment variables from page 1, or reload them from `Zaj-PROJECT.md` before running commands:

```bash
ENV_KEY="staging-primary"        # example; use the selected Zaj-PROJECT.md row
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer target from that row
SSH_ALIAS="<non-prod-alias>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match the selected non-production row
```

## Steps

### 0. Set first-deploy-safe runtime drivers

Some CodeCanyon vendors ship `.env` defaults like `CACHE_STORE=database`, `SESSION_DRIVER=database`, or `QUEUE_CONNECTION=database`. That is valid **after** the installer creates `cache`, `sessions`, and `jobs` tables. It is unsafe on the first deploy because Deployer runs cache/artisan checks before the installer builds those tables.

<Steps>

1. **Force file/sync drivers in the selected server `.env` before the first deploy.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/shared && \
     cp .env .env.before-first-deploy-drivers.$(date +%Y%m%d%H%M%S) && \
     grep -q '^CACHE_STORE=' .env && sed -i 's/^CACHE_STORE=.*/CACHE_STORE=file/' .env || printf '\nCACHE_STORE=file\n' >> .env; \
     grep -q '^CACHE_DRIVER=' .env && sed -i 's/^CACHE_DRIVER=.*/CACHE_DRIVER=file/' .env || printf '\nCACHE_DRIVER=file\n' >> .env; \
     grep -q '^SESSION_DRIVER=' .env && sed -i 's/^SESSION_DRIVER=.*/SESSION_DRIVER=file/' .env || printf '\nSESSION_DRIVER=file\n' >> .env; \
     grep -q '^QUEUE_CONNECTION=' .env && sed -i 's/^QUEUE_CONNECTION=.*/QUEUE_CONNECTION=sync/' .env || printf '\nQUEUE_CONNECTION=sync\n' >> .env; \
     grep -E '^(CACHE_STORE|CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env"
   # Expected: CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync
   ```

   - ✅ The first deploy cannot fail because cache/session/queue database tables do not exist yet.

</Steps>

:::note[After the installer]
Once the installer has created the schema, you may intentionally switch a project back to database/Redis drivers in a later phase. Do that as an explicit change with `migrate:status`, queue/scheduler verification, and a `Zaj-CUSTOMIZATIONS.md` note — not as a hidden first-deploy default.
:::

### 1. Dry-run, then deploy

Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.

<Steps>

1. **Preview, then run the atomic deploy.**

   ```bash
   dep deploy "$DEPLOY_TARGET" --plan    # final review of the task pipeline (see page 1)
   dep deploy "$DEPLOY_TARGET"           # atomic release; symlink flips only on success
   # Expected: "Successfully deployed!" — symlink flips only after the smoke test passes
   ```

   - ✅ `Successfully deployed!`; `current` now points at the new release.

</Steps>

The smoke test gates the symlink flip — a failed build never touches the live release:

```mermaid
flowchart LR
  P["--plan<br/>(preview)"] --> B["build release"]
  B --> S["smoke test"]
  S -->|pass| F["flip current ✅"]
  S -->|fail| K["abort — live release untouched"]
  style F fill:#0b3,stroke:#062,color:#fff
  style K fill:#a40,stroke:#600,color:#fff
```

First-deploy behavior (Release 1): migrations are **skipped automatically** — the web installer owns the initial schema — and `APP_KEY` is auto-generated if missing. Expect `Successfully deployed!`.

If the first-release smoke test returns an unfamiliar `500`, start with [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/): tail `laravel.log`, classify the first fragment, then fix the matching layer instead of redeploying blind.

| At this step | First response | Likely next move |
|---|---|---|
| `500` after symlink flip | Tail `storage/logs/laravel.log` | Use the 500 classification table |
| Empty Laravel log | Check `current/storage/logs/` and `shared/storage/logs/` | Confirm logging target or Sentry-only routing |

:::note[The first release skips migrations on purpose]
Letting Deployer's migrate hook run before the web installer would fight the wizard. Migrations via the deploy hook resume on subsequent releases. If the deploy stops on pending migrations, it prints `migrate --pretend` output — review it, then re-run with `dep deploy "$DEPLOY_TARGET" --allow-pending`.
:::

### 2. Confirm APP_KEY and clear caches

Confirm the health check generated `APP_KEY`, remove any stale install lock, then clear caches with the **versioned** PHP binary.

<Steps>

1. **Confirm `APP_KEY` is present.**

   ```bash
   ssh "$SSH_ALIAS" "grep APP_KEY $DEPLOY_PATH/shared/.env | head -1"
   # Expected: APP_KEY=base64:... (44+ chars)
   ```

   - ✅ `APP_KEY=base64:...` is set with 44+ characters.

2. **Generate `APP_KEY` once if it's empty** (common after a failed first deploy where the health check never ran).

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && php artisan key:generate --force"
   # Expected: "Application key set successfully."
   ```

   - ✅ A key is set if one was missing.

3. **Remove any stale install lock, then clear caches with the versioned PHP binary.**

   ```bash
   ssh "$SSH_ALIAS" "rm -f $DEPLOY_PATH/shared/storage/installed 2>/dev/null"

   # Use the absolute versioned binary from deploy.php — NOT bare `php`.
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan optimize:clear"
   # Expected: each cache layer reports "cleared"
   ```

   - ✅ Stale lock removed; `optimize:clear` flushes every cache layer.

</Steps>

:::caution[Why `optimize:clear` and why the full PHP path]
`optimize:clear` flushes config, cache, compiled, events, routes, views, and blade-icons in one idempotent call. Running only `config:clear && cache:clear` leaves stale compiled views and event caches — the exact cause of "I deployed new blade files but staging shows old content." And bare `php` in an SSH session resolves to the shell default, often older than `composer.json` requires; when the versions disagree, `artisan` crashes on autoloader constraints before your command runs. This is the single most common "staging cache won't clear" failure.
:::

### 3. Verify the Deployer directory structure

Confirm Deployer laid out the atomic release tree as expected.

<Steps>

1. **List the deploy tree.**

   ```bash
   ssh "$SSH_ALIAS" "ls -la $DEPLOY_PATH/"
   # Expected: releases/, shared/, current -> releases/1, and .dep/
   ```

   - ✅ The tree shows `releases/`, `shared/`, `current -> releases/1`, and `.dep/`.

</Steps>

The expected shape:

```
deploy/
├── releases/
│   └── 1/                  ← current release
├── shared/
│   ├── .env                ← persistent environment
│   ├── storage/            ← persistent files (logs, uploads)
│   └── .user.ini           ← PHP settings
├── current -> releases/1   ← symlink to latest release
└── .dep/                   ← Deployer metadata
```

### 4. Verify the `.env` symlink (BLOCKER)

`shared_files` controls which files Deployer symlinks from `shared/` into each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently loading the wrong database, cache driver, or keys. This exact bug cost a 90-minute debugging session. The check below catches it in seconds.

<Steps>

1. **Confirm `current/.env` is a symlink into `shared/.env`, and that Laravel reads your values.**

   ```bash
   # 1. Must be a symbolic link
   ssh "$SSH_ALIAS" "stat -c '%F' $DEPLOY_PATH/current/.env"
   # expected: symbolic link   (regular file = shared_files broken; missing = app will crash)

   # 2. Target must resolve into shared/.env
   ssh "$SSH_ALIAS" "readlink -f $DEPLOY_PATH/current/.env"
   # expected: .../deploy/shared/.env

   # 3. Laravel must actually read your values (not the vendor fallback)
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan tinker --execute=\"
       echo 'cache.default  = '.config('cache.default').PHP_EOL;
       echo 'session.driver = '.config('session.driver').PHP_EOL;
       echo 'queue.default  = '.config('queue.default').PHP_EOL;
     \""
   # Expected: "symbolic link", a path ending in shared/.env, and YOUR cache/session/queue values
   ```

   - ✅ `current/.env` is a symbolic link resolving to `shared/.env`, and Laravel resolves your real cache/session/queue values.

</Steps>

:::danger[If `current/.env` is a regular file or missing — STOP]
A regular file means `shared_files` did not symlink it; missing means every request crashes with *"No application encryption key."* Fix `deploy.php` (`set('shared_files', [])` → `add('shared_files', [...])` so the recipe default `.env` is preserved), commit, and redeploy. Do not run the installer until `current/.env` resolves to `shared/.env`.
:::

If `cache.default` resolves to something other than what `shared/.env` sets, suspect a **variable-name mismatch** for your Laravel version:

| Laravel version | `config/cache.php` reads | `.env` must set |
|---|---|---|
| Laravel 11+ | `env('CACHE_STORE', …)` | `CACHE_STORE=file` |
| Laravel 10 and earlier | `env('CACHE_DRIVER', …)` | `CACHE_DRIVER=file` |

Setting `CACHE_STORE` in a Laravel 10 `.env` is silently ignored — the config reads `CACHE_DRIVER`, gets nothing, and falls through to the template's hardcoded default (often `redis`).

### 5. Verify seeded storage/default content survived shared storage

CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations. The dangerous case is `storage/app/public/*`: Deployer replaces release `storage/` with shared `storage/`, so vendor-shipped logos can disappear unless `shared:init_defaults` copies them into shared storage before `deploy:shared` runs.

<Steps>

1. **Confirm the Deployer defaults hook exists and runs before shared symlinks.**

   ```bash
   grep -n "task('shared:init_defaults'" deploy.php
   grep -n "before('deploy:shared', 'shared:init_defaults')" deploy.php
   # Expected: the task exists and runs before deploy:shared
   ```

   - ✅ The first deploy has a hook that can copy release defaults before `storage/` is shadowed.

2. **Discover seeded content dirs locally and confirm the deploy plan preserves them.**

   ```bash
   # Discover content dirs locally
   for dir in uploads public/uploads public/images public/avatars public/themes \
              storage/app/public public/media public/assets/images; do
     [ -d "$dir" ] && echo "  $dir — $(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ') files"
   done
   grep -A10 "shared_dirs" deploy.php | grep "'"
	   # Expected: storage/app/public is handled by shared:init_defaults; other content dirs appear in shared_dirs
   ```

	   - ✅ `storage/app/public` is seeded by `shared:init_defaults`; every other content directory with demo files is listed in `shared_dirs`.

3. **Verify at least one seeded storage media file exists in shared storage and serves over HTTP.**

   ```bash
   SEEDED_MEDIA=$(find storage/app/public -type f 2>/dev/null | sed 's#^storage/app/public/##' | head -1)
   test -n "$SEEDED_MEDIA" || echo "No local storage/app/public seed files found — skip media URL proof"

   if [ -n "$SEEDED_MEDIA" ]; then
     ssh "$SSH_ALIAS" "test -f '$DEPLOY_PATH/shared/storage/app/public/$SEEDED_MEDIA' && echo 'shared media present'"
     curl -s -o /dev/null -w "%{http_code}\n" "https://$DEPLOY_DOMAIN/storage/$SEEDED_MEDIA"
   fi
   # Expected: "shared media present" and HTTP 200 for the media URL
   ```

   - ✅ A vendor-seeded storage media file exists in shared storage and returns `200`.

</Steps>

Every content directory with demo files must be preserved by one of two paths: `storage/app/public` is copied into shared storage by `shared:init_defaults` before `deploy:shared`, and other durable content dirs should be listed in `shared_dirs`. If seeded storage media is missing after the first deploy, copy it from the local vendor snapshot into shared storage and re-run the URL proof:

```bash
rsync -az storage/app/public/ "$SSH_ALIAS:$DEPLOY_PATH/shared/storage/app/public/"
# Expected: seeded storage/app/public files copied into shared storage
```

### 5.5. Verify (and relink) the public asset symlinks

`public/storage` (and, for in-tree module apps, `public/packages`) are **per-environment symlinks** — they point at a path that only makes sense on the machine that created them. Two server-side traps:

- The vendor often ships `public/storage` **tracked in Git as an absolute symlink to a dead path** (`/var/www/...`, `/home/<other-user>/...`). On your server that target doesn't exist, so every `/storage/*` URL (logos, avatars, uploaded media) returns **403/404** until it's relinked.
- WorkDo-style apps reference in-tree module assets as `/packages/<vendor>/<Module>/...` URLs, but `public/packages` doesn't exist out of the box → all module images 404 and the landing page looks broken. (These per-env symlinks should already be **gitignored** from Phase 2 — see [Initialize the repository](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/) §2. If a tracked `public/storage` symlink still rode along in the release, the relink below replaces it.)

<Steps>

1. **Inspect the server symlinks, then recreate them with the versioned PHP binary.**

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   REL="$DEPLOY_PATH/current"

   # What does public/storage currently resolve to? (a dead /var/www/... target = the trap)
   ssh "$SSH_ALIAS" "readlink -f $REL/public/storage 2>/dev/null; \
     [ -e $REL/public/storage ] && echo '  target exists' || echo '  ❌ target MISSING — relink below'"

   # Recreate the storage symlink fresh (rm the stale/dead one first; storage:link won't overwrite)
   ssh "$SSH_ALIAS" "cd $REL && rm -f public/storage && $PHP_BIN artisan storage:link && \
     readlink -f public/storage"
   # Expected: public/storage → .../shared/storage/app/public (an existing path on THIS server)
   ```

   - ✅ `public/storage` resolves to a path that exists on the server (not a dead `/var/www/...`).

2. **If the app serves in-tree module assets (e.g. WorkDo `packages/`), add the `public/packages` link too.**

   ```bash
   ssh "$SSH_ALIAS" "cd $REL && [ -d packages ] && [ ! -e public/packages ] && \
     ln -s ../packages public/packages && echo '  ✅ public/packages linked' || echo '  (no packages/ dir, or already linked)'"
   # Expected: public/packages exists only when packages/ is shipped
   ```

   - ✅ `public/packages` exists when the app ships in-tree module assets; otherwise `test ! -d packages` proves `N/A — no in-tree package assets on this release`.

</Steps>

:::caution[`public/packages` exposes `.php` source — restrict it before production]
A blanket `ln -s ../packages public/packages` maps the **entire** module tree under the webroot, including `.php` source. That's acceptable on staging, but for production restrict `/packages` to asset extensions (an `.htaccess`/nginx rule allowing only `css|js|png|jpg|svg|woff*`) — or publish module assets into `public/` instead of symlinking. Note the decision in `Zaj-CUSTOMIZATIONS.md`.
:::

:::note[These are per-env — recreate, never commit]
`public/storage` and `public/packages` are recreated on **every** environment (local in Phase 3, here on staging, again on production in Phase 12). They must stay **gitignored** — a committed symlink carries one machine's dead path to all the others. Deployer's `shared_dirs` persists the underlying `shared/storage/` across releases; the symlink itself is cheap to recreate.
:::

### 6. Loosen permissions for the installer

The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

<Steps>

1. **Loosen storage and cache permissions for the installer.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     chmod -R 777 storage bootstrap/cache resources/lang uploads 2>/dev/null; \
     chmod -R 777 $DEPLOY_PATH/shared/storage 2>/dev/null && echo 'Permissions set to 777'"
   # Expected: "Permissions set to 777"
   ```

   - ✅ `Permissions set to 777` — the installer's writable paths are ready.

</Steps>

:::danger[777 is temporary — page 4 re-hardens it]
World-writable app + storage is a serious vulnerability. The installer needs it; the re-harden step on the next page is **not optional**.
:::

## Background

### Troubleshooting — first-release failures

- **`Connection refused 127.0.0.1:6379` on the first artisan task** — the release is loading `.env` from a fallback, not `shared/.env`. This is the symlink BLOCKER above. Switch `set('shared_files', …)` → `add('shared_files', …)`, or untrack a committed `.env` (`git rm --cached .env`), then redeploy.
- **`SQLSTATE[42S02]: Table '…cache' doesn't exist` before the installer** — the vendor defaults cache/session/queue to database drivers before the installer creates those tables. Re-run section 0 and set `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync`, then redeploy.
- **`Too many levels of symbolic links` during `deploy:shared`** — a file is listed in `shared_files` *and* lives inside a `shared_dirs` directory (e.g. `storage/.ignore_locales` with `shared_dirs: ['storage']`). A file may be in one or the other, never both. Remove the `shared_files` entry — `shared_dirs` already persists it. Fails before the symlink switch, so no downtime.
- **`Class not found` (Faker / Debugbar / Telescope)** — production code references a dev-only package excluded by `composer install --no-dev`. Guard with `class_exists()` or move the logic into seeders; add to prod deps only as a last resort.
- **`Vite manifest not found`** — `public/build/` is gitignored and wasn't deployed. For the build-locally strategy, un-ignore it: `git add -f public/build/ && git commit && dep deploy "$DEPLOY_TARGET"`.
- **All `/storage/*` (or `/packages/*`) URLs 403/404 — images/avatars/uploads broken** — the server's `public/storage` points at a dead absolute path (often a vendor-shipped symlink to `/var/www/...`), or `public/packages` was never created. Relink per §5.5: `rm -f public/storage && $PHP_BIN artisan storage:link`, and `ln -s ../packages public/packages` for in-tree module apps. Both are per-env and must stay gitignored.
- **Livewire "published assets are out of date"** — the Livewire package and the published assets in `public/vendor/livewire/` disagree, so `wire:model` silently fails and component state is lost on refresh. One-off fix: resolve `$PHP_BIN` from `deploy.php` (same as §3), then `ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan livewire:publish --assets"`, then purge the CDN cache. Prevention: the deploy template runs a `livewire:publish_assets` task after `vendor:restore` on every release — copy it in if your `deploy.php` predates it.
- **`your php version does not satisfy that requirement` at `deploy:vendors`** — web SAPI PHP is below `composer.json`. Fixes belong on page 1's PHP triple-check: upgrade in hPanel, update `bin/php`, redeploy. Fails before the symlink switch.
- **Emergency rollback** — `dep rollback "$DEPLOY_TARGET"` (changes the symlink to the previous release; no files deleted).

## Checklist

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

- [ ] **🤖 First-deploy drivers safe** — `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync` before installer tables exist.
- [ ] **🤖 Release deployed** — `dep deploy "$DEPLOY_TARGET"` completed for the selected non-production target; `current` symlinks to the new release.
- [ ] **🤖 Key + caches** — `APP_KEY` present (44+ chars); install lock removed; caches cleared with the versioned PHP.
- [ ] **🤖 Deployer tree correct** — `current`, `releases/`, `shared/`, `.dep/`.
- [ ] **🤖 `.env` symlink resolves** — `current/.env` is a symlink into `shared/.env`; Laravel resolves your cache/session/queue values.
- [ ] **🤖 Seeded storage content present** — vendor storage defaults copied to shared storage; at least one expected media URL returns `200`.
- [ ] **🤖 Public symlinks relinked** — `public/storage` resolves to an existing server path (not a dead `/var/www/...`); `public/packages` linked if the app ships in-tree module assets; both stay gitignored.
- [ ] **🤖 Installer permissions set** — 777 for the installer (re-hardened on page 4).

:::next[Next step]
[Installer + smoke path](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/04-installer-smoke/)
:::

# 3 · First release

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/03-first-release/

## TL;DR

**Objective** — ship the app's first atomic release and prove it booted correctly: force first-deploy-safe cache/session/queue drivers when the vendor defaults to database-backed drivers, confirm `APP_KEY`, clear caches with the versioned PHP binary, verify the Deployer tree and the `.env` symlink (a 5-second check that prevents a 90-minute outage), confirm seeded storage assets survived `shared_dirs`, then loosen permissions for the installer.

**Steps at a glance:**
0. **Set first-deploy-safe runtime drivers** — Some vendors default cache/session/queue to database tables the
   installer has not created yet. Use file/sync drivers until the installer completes.
1. **Dry-run, then deploy** — Preview the pipeline one last time, then run the atomic release. The symlink flips
   only on a passing smoke test.
2. **Confirm APP_KEY and clear caches** — Confirm the health check generated `APP_KEY`, remove any stale install
   lock, then clear caches with the versioned PHP binary.
3. **Verify the Deployer directory structure** — Confirm Deployer laid out the atomic release tree as expected.
4. **Verify the `.env` symlink** — `shared_files` controls which files Deployer symlinks from `shared/` into
   each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's
   default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently
   loading the wrong.
5. **Verify demo/default content deployed** — CodeCanyon apps ship demo content (images, avatars, themes, sample
   data) in app-specific locations.
6. **Loosen permissions for the installer** — The web installer requires writable paths. This is a deliberate,
   temporary loosening — it gets hardened on page 4.

:::note[User part + done-when]
**👤 User part** — almost none: this step is entirely SSH/CLI-runnable. A person only needs to read the `.env`-symlink BLOCKER outcome to decide whether to STOP.

**Done when** first-deploy-safe drivers are active, `dep deploy "$DEPLOY_TARGET"` succeeds for the selected non-production row in `Zaj-PROJECT.md`, `current` symlinks to the new release, `APP_KEY` is present, `current/.env` resolves to `shared/.env`, seeded storage/media content is present in shared storage, and permissions are loosened for the installer. &nbsp;·&nbsp; **⏱ ~30–45 min** &nbsp;·&nbsp; 🤖 agent-runnable.
:::

## Background

The payoff of Phase 4 — the app's first atomic release. Deployer flips the `current` symlink **only** after the smoke test passes, so a failed build never touches the live release.

:::note[First live deploy proof lives here]
Phase 4 authored the Deployer and GitHub Actions artifacts. This page is the first [RUN-LIVE] deploy proof: run the release directly with Deployer, or trigger the CI deploy workflow for the selected non-production target and verify it reaches the same symlink/current checks below. Do not backfill that proof into Phase 4.
:::

Reuse the environment variables from page 1, or reload them from `Zaj-PROJECT.md` before running commands:

```bash
ENV_KEY="staging-primary"        # example; use the selected Zaj-PROJECT.md row
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # Deployer target from that row
SSH_ALIAS="<non-prod-alias>"
DEPLOY_DOMAIN="nonprod.example.com"
DEPLOY_PATH="~/domains/$DEPLOY_DOMAIN/deploy"
# Expected: values match the selected non-production row
```

## Steps

### 0. Set first-deploy-safe runtime drivers

Some CodeCanyon vendors ship `.env` defaults like `CACHE_STORE=database`, `SESSION_DRIVER=database`, or `QUEUE_CONNECTION=database`. That is valid **after** the installer creates `cache`, `sessions`, and `jobs` tables. It is unsafe on the first deploy because Deployer runs cache/artisan checks before the installer builds those tables.

<Steps>

1. **Force file/sync drivers in the selected server `.env` before the first deploy.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/shared && \
     cp .env .env.before-first-deploy-drivers.$(date +%Y%m%d%H%M%S) && \
     grep -q '^CACHE_STORE=' .env && sed -i 's/^CACHE_STORE=.*/CACHE_STORE=file/' .env || printf '\nCACHE_STORE=file\n' >> .env; \
     grep -q '^CACHE_DRIVER=' .env && sed -i 's/^CACHE_DRIVER=.*/CACHE_DRIVER=file/' .env || printf '\nCACHE_DRIVER=file\n' >> .env; \
     grep -q '^SESSION_DRIVER=' .env && sed -i 's/^SESSION_DRIVER=.*/SESSION_DRIVER=file/' .env || printf '\nSESSION_DRIVER=file\n' >> .env; \
     grep -q '^QUEUE_CONNECTION=' .env && sed -i 's/^QUEUE_CONNECTION=.*/QUEUE_CONNECTION=sync/' .env || printf '\nQUEUE_CONNECTION=sync\n' >> .env; \
     grep -E '^(CACHE_STORE|CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env"
   # Expected: CACHE_STORE=file, CACHE_DRIVER=file, SESSION_DRIVER=file, QUEUE_CONNECTION=sync
   ```

   - ✅ The first deploy cannot fail because cache/session/queue database tables do not exist yet.

</Steps>

:::note[After the installer]
Once the installer has created the schema, you may intentionally switch a project back to database/Redis drivers in a later phase. Do that as an explicit change with `migrate:status`, queue/scheduler verification, and a `Zaj-CUSTOMIZATIONS.md` note — not as a hidden first-deploy default.
:::

### 1. Dry-run, then deploy

Preview the pipeline one last time, then run the atomic release. The symlink flips only on a passing smoke test.

<Steps>

1. **Preview, then run the atomic deploy.**

   ```bash
   dep deploy "$DEPLOY_TARGET" --plan    # final review of the task pipeline (see page 1)
   dep deploy "$DEPLOY_TARGET"           # atomic release; symlink flips only on success
   # Expected: "Successfully deployed!" — symlink flips only after the smoke test passes
   ```

   - ✅ `Successfully deployed!`; `current` now points at the new release.

</Steps>

The smoke test gates the symlink flip — a failed build never touches the live release:

```mermaid
flowchart LR
  P["--plan<br/>(preview)"] --> B["build release"]
  B --> S["smoke test"]
  S -->|pass| F["flip current ✅"]
  S -->|fail| K["abort — live release untouched"]
  style F fill:#0b3,stroke:#062,color:#fff
  style K fill:#a40,stroke:#600,color:#fff
```

First-deploy behavior (Release 1): migrations are **skipped automatically** — the web installer owns the initial schema — and `APP_KEY` is auto-generated if missing. Expect `Successfully deployed!`.

If the first-release smoke test returns an unfamiliar `500`, start with [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/): tail `laravel.log`, classify the first fragment, then fix the matching layer instead of redeploying blind.

| At this step | First response | Likely next move |
|---|---|---|
| `500` after symlink flip | Tail `storage/logs/laravel.log` | Use the 500 classification table |
| Empty Laravel log | Check `current/storage/logs/` and `shared/storage/logs/` | Confirm logging target or Sentry-only routing |

:::note[The first release skips migrations on purpose]
Letting Deployer's migrate hook run before the web installer would fight the wizard. Migrations via the deploy hook resume on subsequent releases. If the deploy stops on pending migrations, it prints `migrate --pretend` output — review it, then re-run with `dep deploy "$DEPLOY_TARGET" --allow-pending`.
:::

### 2. Confirm APP_KEY and clear caches

Confirm the health check generated `APP_KEY`, remove any stale install lock, then clear caches with the **versioned** PHP binary.

<Steps>

1. **Confirm `APP_KEY` is present.**

   ```bash
   ssh "$SSH_ALIAS" "grep APP_KEY $DEPLOY_PATH/shared/.env | head -1"
   # Expected: APP_KEY=base64:... (44+ chars)
   ```

   - ✅ `APP_KEY=base64:...` is set with 44+ characters.

2. **Generate `APP_KEY` once if it's empty** (common after a failed first deploy where the health check never ran).

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && php artisan key:generate --force"
   # Expected: "Application key set successfully."
   ```

   - ✅ A key is set if one was missing.

3. **Remove any stale install lock, then clear caches with the versioned PHP binary.**

   ```bash
   ssh "$SSH_ALIAS" "rm -f $DEPLOY_PATH/shared/storage/installed 2>/dev/null"

   # Use the absolute versioned binary from deploy.php — NOT bare `php`.
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan optimize:clear"
   # Expected: each cache layer reports "cleared"
   ```

   - ✅ Stale lock removed; `optimize:clear` flushes every cache layer.

</Steps>

:::caution[Why `optimize:clear` and why the full PHP path]
`optimize:clear` flushes config, cache, compiled, events, routes, views, and blade-icons in one idempotent call. Running only `config:clear && cache:clear` leaves stale compiled views and event caches — the exact cause of "I deployed new blade files but staging shows old content." And bare `php` in an SSH session resolves to the shell default, often older than `composer.json` requires; when the versions disagree, `artisan` crashes on autoloader constraints before your command runs. This is the single most common "staging cache won't clear" failure.
:::

### 3. Verify the Deployer directory structure

Confirm Deployer laid out the atomic release tree as expected.

<Steps>

1. **List the deploy tree.**

   ```bash
   ssh "$SSH_ALIAS" "ls -la $DEPLOY_PATH/"
   # Expected: releases/, shared/, current -> releases/1, and .dep/
   ```

   - ✅ The tree shows `releases/`, `shared/`, `current -> releases/1`, and `.dep/`.

</Steps>

The expected shape:

```
deploy/
├── releases/
│   └── 1/                  ← current release
├── shared/
│   ├── .env                ← persistent environment
│   ├── storage/            ← persistent files (logs, uploads)
│   └── .user.ini           ← PHP settings
├── current -> releases/1   ← symlink to latest release
└── .dep/                   ← Deployer metadata
```

### 4. Verify the `.env` symlink (BLOCKER)

`shared_files` controls which files Deployer symlinks from `shared/` into each release. If someone used `set('shared_files', [])` instead of `add('shared_files', [...])`, the recipe's default `['.env']` is wiped — and every release boots from `.env.example` or a stale vendor `.env`, silently loading the wrong database, cache driver, or keys. This exact bug cost a 90-minute debugging session. The check below catches it in seconds.

<Steps>

1. **Confirm `current/.env` is a symlink into `shared/.env`, and that Laravel reads your values.**

   ```bash
   # 1. Must be a symbolic link
   ssh "$SSH_ALIAS" "stat -c '%F' $DEPLOY_PATH/current/.env"
   # expected: symbolic link   (regular file = shared_files broken; missing = app will crash)

   # 2. Target must resolve into shared/.env
   ssh "$SSH_ALIAS" "readlink -f $DEPLOY_PATH/current/.env"
   # expected: .../deploy/shared/.env

   # 3. Laravel must actually read your values (not the vendor fallback)
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     $PHP_BIN artisan tinker --execute=\"
       echo 'cache.default  = '.config('cache.default').PHP_EOL;
       echo 'session.driver = '.config('session.driver').PHP_EOL;
       echo 'queue.default  = '.config('queue.default').PHP_EOL;
     \""
   # Expected: "symbolic link", a path ending in shared/.env, and YOUR cache/session/queue values
   ```

   - ✅ `current/.env` is a symbolic link resolving to `shared/.env`, and Laravel resolves your real cache/session/queue values.

</Steps>

:::danger[If `current/.env` is a regular file or missing — STOP]
A regular file means `shared_files` did not symlink it; missing means every request crashes with *"No application encryption key."* Fix `deploy.php` (`set('shared_files', [])` → `add('shared_files', [...])` so the recipe default `.env` is preserved), commit, and redeploy. Do not run the installer until `current/.env` resolves to `shared/.env`.
:::

If `cache.default` resolves to something other than what `shared/.env` sets, suspect a **variable-name mismatch** for your Laravel version:

| Laravel version | `config/cache.php` reads | `.env` must set |
|---|---|---|
| Laravel 11+ | `env('CACHE_STORE', …)` | `CACHE_STORE=file` |
| Laravel 10 and earlier | `env('CACHE_DRIVER', …)` | `CACHE_DRIVER=file` |

Setting `CACHE_STORE` in a Laravel 10 `.env` is silently ignored — the config reads `CACHE_DRIVER`, gets nothing, and falls through to the template's hardcoded default (often `redis`).

### 5. Verify seeded storage/default content survived shared storage

CodeCanyon apps ship demo content (images, avatars, themes, sample data) in app-specific locations. The dangerous case is `storage/app/public/*`: Deployer replaces release `storage/` with shared `storage/`, so vendor-shipped logos can disappear unless `shared:init_defaults` copies them into shared storage before `deploy:shared` runs.

<Steps>

1. **Confirm the Deployer defaults hook exists and runs before shared symlinks.**

   ```bash
   grep -n "task('shared:init_defaults'" deploy.php
   grep -n "before('deploy:shared', 'shared:init_defaults')" deploy.php
   # Expected: the task exists and runs before deploy:shared
   ```

   - ✅ The first deploy has a hook that can copy release defaults before `storage/` is shadowed.

2. **Discover seeded content dirs locally and confirm the deploy plan preserves them.**

   ```bash
   # Discover content dirs locally
   for dir in uploads public/uploads public/images public/avatars public/themes \
              storage/app/public public/media public/assets/images; do
     [ -d "$dir" ] && echo "  $dir — $(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ') files"
   done
   grep -A10 "shared_dirs" deploy.php | grep "'"
	   # Expected: storage/app/public is handled by shared:init_defaults; other content dirs appear in shared_dirs
   ```

	   - ✅ `storage/app/public` is seeded by `shared:init_defaults`; every other content directory with demo files is listed in `shared_dirs`.

3. **Verify at least one seeded storage media file exists in shared storage and serves over HTTP.**

   ```bash
   SEEDED_MEDIA=$(find storage/app/public -type f 2>/dev/null | sed 's#^storage/app/public/##' | head -1)
   test -n "$SEEDED_MEDIA" || echo "No local storage/app/public seed files found — skip media URL proof"

   if [ -n "$SEEDED_MEDIA" ]; then
     ssh "$SSH_ALIAS" "test -f '$DEPLOY_PATH/shared/storage/app/public/$SEEDED_MEDIA' && echo 'shared media present'"
     curl -s -o /dev/null -w "%{http_code}\n" "https://$DEPLOY_DOMAIN/storage/$SEEDED_MEDIA"
   fi
   # Expected: "shared media present" and HTTP 200 for the media URL
   ```

   - ✅ A vendor-seeded storage media file exists in shared storage and returns `200`.

</Steps>

Every content directory with demo files must be preserved by one of two paths: `storage/app/public` is copied into shared storage by `shared:init_defaults` before `deploy:shared`, and other durable content dirs should be listed in `shared_dirs`. If seeded storage media is missing after the first deploy, copy it from the local vendor snapshot into shared storage and re-run the URL proof:

```bash
rsync -az storage/app/public/ "$SSH_ALIAS:$DEPLOY_PATH/shared/storage/app/public/"
# Expected: seeded storage/app/public files copied into shared storage
```

### 5.5. Verify (and relink) the public asset symlinks

`public/storage` (and, for in-tree module apps, `public/packages`) are **per-environment symlinks** — they point at a path that only makes sense on the machine that created them. Two server-side traps:

- The vendor often ships `public/storage` **tracked in Git as an absolute symlink to a dead path** (`/var/www/...`, `/home/<other-user>/...`). On your server that target doesn't exist, so every `/storage/*` URL (logos, avatars, uploaded media) returns **403/404** until it's relinked.
- WorkDo-style apps reference in-tree module assets as `/packages/<vendor>/<Module>/...` URLs, but `public/packages` doesn't exist out of the box → all module images 404 and the landing page looks broken. (These per-env symlinks should already be **gitignored** from Phase 2 — see [Initialize the repository](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/) §2. If a tracked `public/storage` symlink still rode along in the release, the relink below replaces it.)

<Steps>

1. **Inspect the server symlinks, then recreate them with the versioned PHP binary.**

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php[^'\"]*" | head -1)
   PHP_BIN="${PHP_BIN:-php}"
   REL="$DEPLOY_PATH/current"

   # What does public/storage currently resolve to? (a dead /var/www/... target = the trap)
   ssh "$SSH_ALIAS" "readlink -f $REL/public/storage 2>/dev/null; \
     [ -e $REL/public/storage ] && echo '  target exists' || echo '  ❌ target MISSING — relink below'"

   # Recreate the storage symlink fresh (rm the stale/dead one first; storage:link won't overwrite)
   ssh "$SSH_ALIAS" "cd $REL && rm -f public/storage && $PHP_BIN artisan storage:link && \
     readlink -f public/storage"
   # Expected: public/storage → .../shared/storage/app/public (an existing path on THIS server)
   ```

   - ✅ `public/storage` resolves to a path that exists on the server (not a dead `/var/www/...`).

2. **If the app serves in-tree module assets (e.g. WorkDo `packages/`), add the `public/packages` link too.**

   ```bash
   ssh "$SSH_ALIAS" "cd $REL && [ -d packages ] && [ ! -e public/packages ] && \
     ln -s ../packages public/packages && echo '  ✅ public/packages linked' || echo '  (no packages/ dir, or already linked)'"
   # Expected: public/packages exists only when packages/ is shipped
   ```

   - ✅ `public/packages` exists when the app ships in-tree module assets; otherwise `test ! -d packages` proves `N/A — no in-tree package assets on this release`.

</Steps>

:::caution[`public/packages` exposes `.php` source — restrict it before production]
A blanket `ln -s ../packages public/packages` maps the **entire** module tree under the webroot, including `.php` source. That's acceptable on staging, but for production restrict `/packages` to asset extensions (an `.htaccess`/nginx rule allowing only `css|js|png|jpg|svg|woff*`) — or publish module assets into `public/` instead of symlinking. Note the decision in `Zaj-CUSTOMIZATIONS.md`.
:::

:::note[These are per-env — recreate, never commit]
`public/storage` and `public/packages` are recreated on **every** environment (local in Phase 3, here on staging, again on production in Phase 12). They must stay **gitignored** — a committed symlink carries one machine's dead path to all the others. Deployer's `shared_dirs` persists the underlying `shared/storage/` across releases; the symlink itself is cheap to recreate.
:::

### 6. Loosen permissions for the installer

The web installer requires writable paths. This is a deliberate, temporary loosening — it gets hardened on page 4.

<Steps>

1. **Loosen storage and cache permissions for the installer.**

   ```bash
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && \
     chmod -R 777 storage bootstrap/cache resources/lang uploads 2>/dev/null; \
     chmod -R 777 $DEPLOY_PATH/shared/storage 2>/dev/null && echo 'Permissions set to 777'"
   # Expected: "Permissions set to 777"
   ```

   - ✅ `Permissions set to 777` — the installer's writable paths are ready.

</Steps>

:::danger[777 is temporary — page 4 re-hardens it]
World-writable app + storage is a serious vulnerability. The installer needs it; the re-harden step on the next page is **not optional**.
:::

## Background

### Troubleshooting — first-release failures

- **`Connection refused 127.0.0.1:6379` on the first artisan task** — the release is loading `.env` from a fallback, not `shared/.env`. This is the symlink BLOCKER above. Switch `set('shared_files', …)` → `add('shared_files', …)`, or untrack a committed `.env` (`git rm --cached .env`), then redeploy.
- **`SQLSTATE[42S02]: Table '…cache' doesn't exist` before the installer** — the vendor defaults cache/session/queue to database drivers before the installer creates those tables. Re-run section 0 and set `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync`, then redeploy.
- **`Too many levels of symbolic links` during `deploy:shared`** — a file is listed in `shared_files` *and* lives inside a `shared_dirs` directory (e.g. `storage/.ignore_locales` with `shared_dirs: ['storage']`). A file may be in one or the other, never both. Remove the `shared_files` entry — `shared_dirs` already persists it. Fails before the symlink switch, so no downtime.
- **`Class not found` (Faker / Debugbar / Telescope)** — production code references a dev-only package excluded by `composer install --no-dev`. Guard with `class_exists()` or move the logic into seeders; add to prod deps only as a last resort.
- **`Vite manifest not found`** — `public/build/` is gitignored and wasn't deployed. For the build-locally strategy, un-ignore it: `git add -f public/build/ && git commit && dep deploy "$DEPLOY_TARGET"`.
- **All `/storage/*` (or `/packages/*`) URLs 403/404 — images/avatars/uploads broken** — the server's `public/storage` points at a dead absolute path (often a vendor-shipped symlink to `/var/www/...`), or `public/packages` was never created. Relink per §5.5: `rm -f public/storage && $PHP_BIN artisan storage:link`, and `ln -s ../packages public/packages` for in-tree module apps. Both are per-env and must stay gitignored.
- **Livewire "published assets are out of date"** — the Livewire package and the published assets in `public/vendor/livewire/` disagree, so `wire:model` silently fails and component state is lost on refresh. One-off fix: resolve `$PHP_BIN` from `deploy.php` (same as §3), then `ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan livewire:publish --assets"`, then purge the CDN cache. Prevention: the deploy template runs a `livewire:publish_assets` task after `vendor:restore` on every release — copy it in if your `deploy.php` predates it.
- **`your php version does not satisfy that requirement` at `deploy:vendors`** — web SAPI PHP is below `composer.json`. Fixes belong on page 1's PHP triple-check: upgrade in hPanel, update `bin/php`, redeploy. Fails before the symlink switch.
- **Emergency rollback** — `dep rollback "$DEPLOY_TARGET"` (changes the symlink to the previous release; no files deleted).

## Checklist

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

- [ ] **🤖 First-deploy drivers safe** — `CACHE_STORE=file`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file`, `QUEUE_CONNECTION=sync` before installer tables exist.
- [ ] **🤖 Release deployed** — `dep deploy "$DEPLOY_TARGET"` completed for the selected non-production target; `current` symlinks to the new release.
- [ ] **🤖 Key + caches** — `APP_KEY` present (44+ chars); install lock removed; caches cleared with the versioned PHP.
- [ ] **🤖 Deployer tree correct** — `current`, `releases/`, `shared/`, `.dep/`.
- [ ] **🤖 `.env` symlink resolves** — `current/.env` is a symlink into `shared/.env`; Laravel resolves your cache/session/queue values.
- [ ] **🤖 Seeded storage content present** — vendor storage defaults copied to shared storage; at least one expected media URL returns `200`.
- [ ] **🤖 Public symlinks relinked** — `public/storage` resolves to an existing server path (not a dead `/var/www/...`); `public/packages` linked if the app ships in-tree module assets; both stay gitignored.
- [ ] **🤖 Installer permissions set** — 777 for the installer (re-hardened on page 4).

:::next[Next step]
[Installer + smoke path](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/05-deploy-staging/04-installer-smoke/)
:::

3 · First release

TL;DR

Background

Steps

0. Set first-deploy-safe runtime drivers

1. Dry-run, then deploy

2. Confirm APP_KEY and clear caches

3. Verify the Deployer directory structure

4. Verify the .env symlink (BLOCKER)

5. Verify seeded storage/default content survived shared storage

5.5. Verify (and relink) the public asset symlinks

6. Loosen permissions for the installer

Background

Troubleshooting — first-release failures

Checklist

4. Verify the `.env` symlink (BLOCKER)