Set up shared hosting

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: Set up shared hosting
- url: https://library.zajapps.com/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: infrastructure
- subcategory: hosting
- topic: shared-hosting
- phase: shared-hosting
- part_number: 1 (legacy stepNumber frontmatter)
- legacy_step_number: 1
- est_time: ~2 min verify · ~15–25 min first install
- description: Once-per-account Admin-Server bootstrap — monitoring cron, ops/deploys/backups webhooks, MD5 baselines, and server.env before any Laravel deploy.
- tags: servers, shared-hosting, admin-server, hostinger, monitoring

## Execution rules (binding)
- This is Part 1 of phase shared-hosting (~2 min verify · ~15–25 min first install) — 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.
- 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.

---

# Set up shared hosting

## TL;DR

**Objective** — bootstrap the per-server **Admin-Server** toolkit on a fresh hosting account so config drift detection, MD5 integrity checks, disk/inode alerts, PHP error-log scanning, domain inventory, log rotation, and alert channels (`ops` · `deploys` · `backups`) are defined **once** for every app on that account.

:::note[For beginners and agents]
**Gate — done when** — `~/Admin-Server/scripts/status.sh` exits `0` and reports the expected identity, the log freshness probe reports no `STALE` rows, `monitored-paths.conf` includes `~/.ssh/authorized_keys` plus every app domain path being reused, and one synthetic alert arrives through an `ops` webhook with the correct env prefix: **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`**. Deploy, backup, and heartbeat slots are either configured or explicitly waived in `Zaj-PROJECT.md`; blank slots are no-ops, not proof that alerting works.

**Once per server, not per project.** Re-run only when you add a **new** hosting account. If scripts already exist, detect-and-skip — verify, do not reinstall.

**⏱ ~2 min** (verify) · **~15–25 min** (first install) · **🔀** all work over SSH on the server; **👤** Hostinger API/panel authorization + webhook paste in `nano` on the server.
:::

---

This is the **account-scoped server-readiness playbook** before [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) reaches deployment. Conceptual companion: [Three-tier admin (handbook)](/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/).

<StageFlow
  title="Once per account, then every app"
  stages={[
    { label: 'This account', sub: 'Admin-Server readiness', tone: 'core' },
    { label: 'App #1', sub: 'setup-new', tone: 'good' },
    { label: 'App #N', sub: 'reuse server tier', tone: 'muted' },
  ]}
/>

```mermaid
flowchart LR
  A["New hosting account"] --> B["Server readiness · this playbook"]
  B --> C["setup-new · app 1"]
  B --> D["setup-new · app N"]
```

## Operating rules

Every task in this phase follows four operating rules:

| Rule | Meaning |
| --- | --- |
| **Runs on the server** | SSH into `~/Admin-Server/` on the hosting account — zero toolkit binaries on your laptop |
| **Secrets stay server-side** | No webhook URL or SA token in laptop argv or agent chat — see [Secrets discipline](#secrets-discipline) |
| **Idempotent** | Re-run safe: `git pull`-friendly; baselines non-destructive; cron lines detected before duplicate add |
| **Secret source of truth** | Webhooks and heartbeat URLs are created/stored first in the shared infrastructure 1Password vault recorded in `Zaj-PROJECT.md` (default example: `General-Dev`); runtime copies live only in gitignored `server.env` at `chmod 600` |

:::danger[Presence is not liveness]
`~/Admin-Server/scripts/status.sh` can exist and still be stale if Hostinger cron jobs stopped weeks ago. A reusable Admin-Server must pass both checks: `status.sh` exits `0` **and** every expected log file is fresh within twice its cron interval. A `STALE` row blocks reuse until the cron is fixed and the script runs again.
:::

:::note[Pairing with laptop setup]
[Machine setup](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/) configures **your laptop** (`gh`, MCP, `op`). **This playbook configures each hosting account.** The two tracks are independent — run them in either order — but **both must complete before [Deploy pipeline](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/)** registers webhooks through Admin-Server's `deploys` channel. After this playbook, record the SSH alias and `Admin-Hostinger-<account>` repo name in the project's gitignored `CLAUDE.local.md`.
:::

### Tasks at a glance

| # | Task | Priority | Type |
| --- | --- | --- | --- |
| 0.1 | Clone Admin-Server toolkit + initial repo setup | MUST | CLI (SSH) |
| 0.2 | Download `op` 1Password CLI *(no root)* | MUST after P9C-1 | CLI |
| 0.3 | Bootstrap `config/server.env` from template | MUST | 👤 on server (`nano`) |
| 0.4 | Make scripts executable + `chmod 600` on `server.env` | MUST | CLI |
| 0.5 | Generate initial MD5 baseline | MUST | CLI |
| 0.6 | Run `status.sh` smoke test | MUST | CLI |
| 0.7 | Fire one synthetic alert through `ops` channel | MUST | CLI |
| 0.8 | Register Hostinger cron entries (6 lines, 5-field syntax) | MUST | API or 👤 hPanel UI |
| 0.9 | Discover server runtime paths | MUST | CLI |
| 0.10 | First commit + push to per-server private repo | MUST | CLI |
| 0.11 | Document server in `CLAUDE.local.md` | SHOULD | Manual |

:::caution[Agents — do not invent Admin-Server layout]
If task text references scripts that are missing on disk, follow the **Admin-Server cross-phase proposal** in `_Sources/laravel/codecanyon/server-setup/admin-server-cross-phase-integration-proposal.md` (§ "Initial server setup checklist") — do not flesh out paths from training-data guesses. Interim flow uses webhook URLs in `server.env`; P9C-1 replaces that with 1Password Service Account fetch.
:::

## Before you start

| Prerequisite | Verify |
| --- | --- |
| SSH public-key auth to the account | `ssh <SSH_ALIAS> 'echo ok'` — no password prompt |
| Private GitHub repo `Admin-Hostinger-<account>` | Empty repo OK for first push |
| Discord or Slack ops channel | Ops webhook ready for `#server-alerts` or the project's equivalent; configure only through the secret-safe flow below |
| Shared infrastructure 1Password vault | Record the actual vault name in `Zaj-PROJECT.md`; `General-Dev` is the default example, not a fixed requirement |
| Heartbeat provider decision | MonSpark, Healthchecks.io, Better Stack, Cronitor, UptimeRobot heartbeats, or `N/A` with reason |

## Detect and skip

Run before any install work:

```bash
   ssh <SSH_ALIAS> '
     if [ -x ~/Admin-Server/scripts/status.sh ]; then
       echo "Admin-Server present — run Verify existing next"
       ~/Admin-Server/scripts/status.sh
     else
       ls ~/Admin-Server/scripts/*.sh 2>/dev/null | head -10
     fi
   '
```

| Output | Action |
| --- | --- |
| `status.sh` or scripts listed | Jump to [Verify existing](#verify-existing) — skip setup steps 0.1–0.5 only after liveness passes |
| No such file | Continue with the [setup tasks](#tasks) |
| Scripts but no `lib/init.sh` or no `config/server.env` | Legacy layout — run [Migrate legacy installs to v2](#migrate-legacy-installs-to-v2) before cron or app reuse |

---

## Migrate legacy installs to v2

Run this branch when `~/Admin-Server/` exists but uses the older layout (`config/webhooks.conf`, missing `config/server.env`, missing `lib/init.sh`, or scripts that do not write the expected logs). Migration is not a pass by itself; after it, run [Verify existing](#verify-existing).

<Steps>

1. **Normalize the config layout without deleting legacy files.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   mkdir -p config logs baselines
   if [ ! -f config/server.env ]; then
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     echo "Created config/server.env from example; edit it before alerting checks."
   fi
   [ -f config/webhooks.conf ] && echo "Legacy config/webhooks.conf kept as read-only fallback."
   test -d lib || echo "Missing lib/ — pull the Admin-Server v2 repo before continuing."
   git status --short
   REMOTE
   ```

   Expected: `config/server.env` exists at `chmod 600`; legacy `webhooks.conf` is not deleted; missing `lib/` is treated as a blocker until the v2 repo is pulled.

2. **Complete the v2 gates.** Edit `server.env` with the slot matrix in step 0.3, register absolute-path cron rows in step 0.8, regenerate the baseline, then run [Verify existing](#verify-existing). A migrated server does not become deploy-ready until the freshness probe has no `STALE` rows.

</Steps>

## Tasks

Verification-first flow: **Clone → op CLI (P9C-1) → `server.env` → baseline → status + alert → cron liveness → runtime discovery → commit/push**.

### 0.1 · Clone Admin-Server toolkit

<Steps>

1. **Clone the per-server private repo** into `~/Admin-Server/`.

   ```bash
   ssh <SSH_ALIAS> '
     git clone git@github.com-<GITHUB_USER>:<GITHUB_USER>/Admin-Hostinger-<account>.git ~/Admin-Server
     cd ~/Admin-Server && git remote -v
   '
   # Expected: origin → your Admin-Hostinger-<account> repo
   ```

2. **If the directory already exists**, update instead of re-cloning.

   ```bash
   ssh <SSH_ALIAS> 'cd ~/Admin-Server && git fetch && git pull'
   ```

</Steps>

### 0.2 · `op` CLI *(deferred — P9C-1)*

Step **0.2** (download `op` 1Password CLI, no root) is **MUST after P9C-1**, not part of the interim bootstrap. For forward compatibility only, add an empty placeholder when editing `server.env` in step 0.3:

```bash
OP_SERVICE_ACCOUNT_TOKEN=""
```

Do not run `op signin` from an agent session.

### 0.3 · Bootstrap `config/server.env`

<Steps>

1. **Create `server.env` from the template** on the server only.

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

2. **Set identity and at least one ops webhook** from the shared infrastructure vault (paste URL in `nano` on server — never into chat).

   Minimum alerting-ready fields: `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` (`staging` \| `production`), plus `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS`. The source copy lives in 1Password, usually `op://General-Dev/...` unless `Zaj-PROJECT.md` names a different shared infrastructure vault.

</Steps>

:::danger[Installed ≠ alerting works]
`server.env` is the Admin-Server v2 runtime source of truth. A green `status.sh` proves scripts and cron freshness; it does **not** prove Slack, Discord, or external heartbeat destinations are wired. Empty alert or heartbeat values silently no-op. Do not mark the account alerting-ready until the synthetic `ops` alert reaches the expected channel and each adopted heartbeat monitor shows a fresh ping.
:::

| Slot | Variables | Required? | Behavior when blank |
| --- | --- | --- | --- |
| Server identity | `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` | Required | `status.sh` cannot prove the account identity |
| Ops alerts | `DISCORD_WEBHOOK_OPS`, `SLACK_WEBHOOK_OPS` | Required for alerting-ready | Monitoring alerts log locally only; this playbook's alert gate cannot pass |
| Deploy notifications | `DISCORD_WEBHOOK_DEPLOYS`, `SLACK_WEBHOOK_DEPLOYS` | Required when deploy notifications are enabled | Deployer Section J logs "notification skipped" and continues |
| Backup notifications | `DISCORD_WEBHOOK_BACKUPS`, `SLACK_WEBHOOK_BACKUPS` | Required when backup alerting is enabled | Backup alerts no-op or fall back to ops depending on the script |
| Legacy/default webhook | `WEBHOOK_URL` | Legacy fallback only | Current v2 scripts should prefer the channel-specific vars above |
| External heartbeat pings | `HEARTBEAT_SNAPSHOT`, `HEARTBEAT_INTEGRITY`, `HEARTBEAT_RESOURCE`, `HEARTBEAT_ERRORLOG`, `HEARTBEAT_INVENTORY` | Required when external heartbeat monitoring is claimed | Cron still runs locally, but MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot will not page on missed runs |
| Future 1Password fetch | `OP_SERVICE_ACCOUNT_TOKEN` | Empty until service-account hardening | `server.env` remains the runtime copy; source values stay in the shared infra vault |

### Wire alerting destinations

Alert channels are part of the server setup, not a later nice-to-have. Use the channel names below as the default map, then record the actual workspace/channel names in `Zaj-PROJECT.md`.

If an agent is driving Discord, Slack, or MonSpark through the operator's logged-in browser, use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/): click by accessibility-tree element refs, not screenshot coordinates; let the human own login and secret-copy moments; move copied URLs through clipboard → stdin so webhook and heartbeat URLs never print in chat, terminal output, or process lists.

| Route | Common destination | Variables |
| --- | --- | --- |
| Ops | `#server-alerts` | `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS` |
| Deploys | `#deployments` | `DISCORD_WEBHOOK_DEPLOYS` or `SLACK_WEBHOOK_DEPLOYS` |
| Backups | ops or backup channel | `DISCORD_WEBHOOK_BACKUPS` or `SLACK_WEBHOOK_BACKUPS` |
| App alerts | `#app-alerts` | App/Sentry/MonSpark routing, not Admin-Server deploy vars |

<Steps>

1. **Create or reuse provider webhooks** in the right workspace.

   - Discord: right-click channel → **Edit Channel** → **Integrations** → **Create Webhook** → rename → **Save** → **Copy URL**.
   - Slack: `api.slack.com/apps` → **Incoming Webhooks** → **Add to Workspace** → channel → **Copy**.
   - MonSpark heartbeats: **Cron Job** → **Create Monitor** → name/interval/grace → **Copy heartbeat URL**.
   - If the operator already has the right channel and webhook, reuse it; do not create duplicates.

2. **Store every URL in 1Password before it touches the server.**

   ```md
   Shared infra vault: <actual-vault-name>  # default example: General-Dev
   op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS
   op://<vault>/Admin-Server/SLACK_WEBHOOK_DEPLOYS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_DEPLOYS
   ```

3. **Smoke-test endpoints without printing secrets.**

   ```bash
   DISCORD_URL="$(op read 'op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS')"
   curl -fsS -o /dev/null -w '%{http_code}\n' "$DISCORD_URL"
   unset DISCORD_URL
   # Expected: 200 for Discord webhook GET metadata

   SLACK_URL="$(op read 'op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS')"
   printf '{"text":"Admin-Server webhook smoke test"}' \
     | curl -fsS -X POST -H 'Content-type: application/json' --data @- "$SLACK_URL"
   unset SLACK_URL
   # Expected: ok
   ```

   If a provider does not support a harmless preflight for that URL, skip the endpoint probe and rely on the real `send_alert`/`alert-helper` test after wiring.

4. **Paste into `config/server.env` through an interactive editor or secure clipboard bridge.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

   Never echo webhook URLs into terminal logs, agent chat, README files, screenshots, or commits.

5. **Verify with the shipped alert helper.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     if [ -x scripts/send_alert.sh ]; then
       bash scripts/send_alert.sh ops INFO "Admin-Server alerting smoke test for $(hostname)"
     else
       bash scripts/alert-helper.sh INFO "Admin-Server alerting smoke test for $(hostname)" ops
     fi
   '
   # Expected: exit 0 and the ops channel receives the message with the server env prefix.
   ```

</Steps>

### 0.4 · Executable scripts + `server.env` permissions

<Steps>

1. **chmod scripts and confirm `server.env` stays private.**

   ```bash
   ssh <SSH_ALIAS> '
     chmod +x ~/Admin-Server/scripts/*.sh
     chmod 600 ~/Admin-Server/config/server.env
     ls -l ~/Admin-Server/scripts/status.sh ~/Admin-Server/config/server.env
   '
   # Expected: scripts -rwx; server.env -rw------- 
   ```

</Steps>

### 0.5 · Generate initial MD5 baseline

<Steps>

1. **Generate and commit the integrity baseline.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     conf="config/monitored-paths.conf"
     touch "$conf"
     grep -Fxq "$HOME/.ssh/authorized_keys" "$conf" 2>/dev/null || printf "%s\n" "$HOME/.ssh/authorized_keys" >> "$conf"
     ~/Admin-Server/scripts/generate-baseline.sh
     git add "$conf" baselines/checksums.md5
     git diff --cached --quiet || git commit -m "Initial integrity baseline"
   '
   # Expected: checksums.md5 with server dotfiles and ~/.ssh/authorized_keys
   ```

</Steps>

### 0.6 · Run `status.sh` smoke test

<Steps>

1. **Run the health snapshot** — this is the **verify** step in the eight-step flow.

   ```bash
   ssh <SSH_ALIAS> '~/Admin-Server/scripts/status.sh'
   ```

	   Expected: clean `SERVER_LABEL` / `SERVER_ENV`; baseline ✅; webhook slots show ✅/❌ (at least one ✅ before you leave this playbook); **cron schedule printed** — use that output for the cron step.

</Steps>

### 0.7 · Fire one synthetic alert (`ops` channel)

<Steps>

1. **Send a test alert** through the ops channel.

   ```bash
   ssh <SSH_ALIAS> '
     ~/Admin-Server/scripts/alert-helper.sh INFO "Server-readiness smoke test" "Hello from $(hostname)" ops
   '
   ```

   **Expected:** Discord/Slack message with **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`** prefix.

</Steps>

### 0.8 · Register six Hostinger cron entries

Hostinger shared hosting often has **no** SSH `crontab` CLI. Use the Hostinger REST API when you have the account token; otherwise use hPanel → Advanced → Cron Jobs. Use SSH `crontab` only on hosts where `command -v crontab` succeeds.

:::caution[Hostinger cron commands are not shell scripts]
The Hostinger API/panel stores a command, but it does not safely expand `$HOME` or run shell operators for you. Use an absolute path such as `/home/<user>/Admin-Server/scripts/integrity-check.sh`, and keep redirects/pipes inside wrapper scripts if a command needs them.
:::

| Cron job | Typical script | Watches |
| --- | --- | --- |
| Config snapshot | `snapshot-config.sh` | Tracked config drift |
| MD5 integrity | `integrity-check.sh` | Baseline mutations |
| Disk / inode | `resource-check.sh` | Space and inode exhaustion |
| PHP error log | `error-log-check.sh` | New PHP errors across domains |
| Domain inventory | `domain-inventory.sh` | Apps/domains on account |
| Log rotation | `rotate-logs.sh` | Log volume |

<Steps>

1. **Resolve the absolute Admin-Server path** before creating any cron row.

   ```bash
   ssh <SSH_ALIAS> 'printf "ADMIN_SERVER=%s\n" "$HOME/Admin-Server"'
   # Expected: ADMIN_SERVER=/home/<user>/Admin-Server
   ```

2. **Copy cron expressions from `status.sh` output** (step 0.6) — do not guess schedules.

3. **Create or verify the six cron rows** with API GET-before-POST when available. Match the absolute command exactly.

   ```bash
   # Example row payload shape; repeat for each script from the table above.
   # Do not include redirects, pipes, or $HOME in command.
   command="bash /home/<user>/Admin-Server/scripts/snapshot-config.sh"
   ```

   If the API is not available, add the same absolute commands in hPanel and verify **five-field** syntax (`min hour dom mon dow`). A UI preset is not enough; inspect the saved row.

4. **Confirm log files update** after the first interval with the freshness probe.

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then
       echo "❌ STALE $label — missing $path"; exit 1
     fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   ```

   Expected: every row prints `✅ fresh`; any `❌ STALE` row means the cron is not alive enough for app deploys.

</Steps>

### External heartbeat wiring *(MonSpark, Healthchecks, Better Stack, Cronitor, UptimeRobot)*

External heartbeat monitors are layered on top of the local cron/log freshness gate. They are useful, but they are not a substitute for fresh Admin-Server logs. If the operator already pays for MonSpark, Better Stack, Cronitor, or UptimeRobot heartbeat monitors, use that tool here instead of signing up for a new Healthchecks.io account.

| Script | Heartbeat slot | Provider examples |
| --- | --- | --- |
| `snapshot-config.sh` | `HEARTBEAT_SNAPSHOT` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `integrity-check.sh` | `HEARTBEAT_INTEGRITY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `resource-check.sh` | `HEARTBEAT_RESOURCE` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `error-log-check.sh` | `HEARTBEAT_ERRORLOG` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `domain-inventory.sh` | `HEARTBEAT_INVENTORY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |

If a slot is blank, that script should still run locally but will not ping the external heartbeat provider. If you claim external heartbeat monitoring is configured, paste the heartbeat URLs into `config/server.env`, run the matching script once, and confirm the provider dashboard receives the ping. Leave blank slots explicitly documented as `N/A — no external heartbeat configured`.

For MonSpark specifically, create one **Cron Job** monitor per Admin-Server script and paste its URL into the matching `HEARTBEAT_*` slot. The [MonSpark monitoring guide](/tech-stack/laravel/codecanyon/learn/guides/monspark-monitoring/) covers the full provider setup and optional Laravel `MONSPARK_CRON_URL` scheduler heartbeat.

### 0.9 · Discover server runtime paths

<Steps>

1. **Record the server runtime paths the app deploys will consume.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   {
     echo "# Generated by setup-shared-hosting; update when hPanel PHP/Node changes."
     echo "PHP_LOGIN_SHELL=$(command -v php || true)"
     for phpbin in /opt/alt/php84/usr/bin/php /opt/alt/php83/usr/bin/php /opt/alt/php82/usr/bin/php /usr/local/bin/php /usr/bin/php; do
       [ -x "$phpbin" ] && printf 'PHP_CANDIDATE=%s # %s\n' "$phpbin" "$("$phpbin" -r 'echo PHP_VERSION;' 2>/dev/null || true)"
     done
     echo "COMPOSER_BIN=$(command -v composer || true)"
     echo "NODE_BIN=$(command -v node || true)"
     echo "NPM_BIN=$(command -v npm || true)"
   } > config/server-environment.conf
   cat config/server-environment.conf
   git add config/server-environment.conf
   git diff --cached --quiet || git commit -m "Record server environment paths"
   REMOTE
   ```

   Expected: `config/server-environment.conf` is committed and shows the login-shell PHP separately from versioned PHP candidates. Later deploy pages still confirm the domain's selected web/CLI PHP before pinning Composer.

</Steps>

### 0.10 · First commit + push

<Steps>

1. **Push the Admin-Server repo** (baseline + monitored paths + committed config such as `server-environment.conf`).

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     git status
     git push
   '
   ```

</Steps>

### 0.11 · Document the server *(SHOULD)*

Record in the project's **`CLAUDE.local.md`** (or equivalent local-only notes): SSH alias, `Admin-Hostinger-<account>` repo name, last baseline date, last webhook rotation — not in git-tracked secrets.

---

## Verify existing

When detect-and-skip found scripts already installed:

```bash
ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE
```

Fix only failed checks (missing baseline → 0.5; stale logs → 0.8; unset webhooks → 0.3 + 0.7). Then return to your app playbook.

If this verification is happening for a specific app domain, add that domain path to the integrity baseline before you return:

```bash
APP_DOMAIN="<domain.example.com>"
ssh <SSH_ALIAS> "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
APP_DOMAIN="${APP_DOMAIN:?set APP_DOMAIN before running}"
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the domain path; baseline regenerated
```

## Idempotent re-run

| Concern | On second run |
| --- | --- |
| Repo | `git fetch && git pull` — no re-clone |
| Cron | Detected before add — no duplicates |
| Baseline | Regeneration non-destructive |
| Health | `status.sh` + the log freshness probe |

## Secrets discipline

- Webhook URLs are **credentials** — live only in 1Password and gitignored `server.env`; never in README files, examples, commits, screenshots, or chat.
- A committed webhook URL is compromised. Delete/recreate the webhook, then update 1Password and `server.env`; editing nearby config is not recovery.
- Before committing Admin-Server docs/config examples, run `rg -n 'discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9._-]+' .` and confirm there are no tracked Discord webhook URLs.
- **`server.env`**: `chmod 600`, gitignored — interim SoT for `ops` / `deploys` / `backups`.  
- Prefer **server-to-server** copy or **clipboard bridge** at keyboard — never through agent chat.  
- **P9C-1 (future):** 1Password SA fetch replaces plaintext URLs — see [Hardening](#hardening-serverenv).

## Hardening `server.env`

| Weakness | Interim | After P9C-1 |
| --- | --- | --- |
| Plaintext webhooks on disk | `chmod 600` + gitignore | SA fetch at runtime |
| No audit trail | Rotation log in monitoring state | 1Password activity log |
| Per-server manual rotation | Operator checklist | Rotate vault once; servers pull fresh |

Later hardening: move Discord/Slack webhook URLs out of plaintext `server.env` into a scoped read-only 1Password service-account fetch that fails closed. This is post-launch Admin-Server ops work, not a setup-new Phase 9 launch gate.

P9C-1 unblocks after the CodeCanyon payments setup proves `op` on Hostinger CloudLinux.

---

## Checklist

Verification checklist:

- [ ] SSH alias works passwordlessly from laptop
- [ ] Server GitHub auth: `ssh -T git@github.com-<GITHUB_USER>` succeeds
- [ ] `~/Admin-Server/` present; `git remote -v` correct
- [ ] All monitoring scripts executable (`-rwx`)
- [ ] `config/server.env` exists at `chmod 600`, gitignored
- [ ] Six cron entries installed through Hostinger API/hPanel or SSH `crontab` when available; each row uses `bash /home/<user>/Admin-Server/scripts/<script>.sh` with no `$HOME`, pipes, or redirects
- [ ] Admin-Server logs are fresh within each cron interval ×2; no `STALE` rows
- [ ] `baselines/checksums.md5` exists with ≥4 entries
- [ ] Test alert received with `[STAGING] 🟡` or `[PRODUCTION] 🔴` prefix
- [ ] Adopted external heartbeat slots show fresh provider pings, or each blank slot is recorded as `N/A` with reason
- [ ] `config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's domain path before reuse
- [ ] `config/server-environment.conf` committed with PHP/Node/Composer path candidates
- [ ] Server documented in `CLAUDE.local.md` *(step 0.11)*

## What's next

<CardGrid>
  <LinkCard title="Machine setup" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/" description="Once per laptop — gh, MCP, op — pairs with this server gate." />
  <LinkCard title="CodeCanyon setup-new" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/" description="Per-app playbook — run after this account gate passes." />
  <LinkCard title="Three-tier admin model" href="/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/" description="Admin-Local · Admin-Domain · Admin-Server + cascade resolver." />
  <LinkCard title="Deploy pipeline · step 1" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/01-deployer/" description="Assumes Admin-Server paths resolve for deploys/backups webhooks." />
</CardGrid>

### Maintainer note

Source archives and intake ledgers stay out of reader-facing playbooks. The workflow above is the published server-readiness path.

:::next[Next: start a CodeCanyon project]
When the gate passes, continue with [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) — Phase 1 workspace setup on your laptop.
:::

# Set up shared hosting

> Source: https://library.zajapps.com/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/

## TL;DR

**Objective** — bootstrap the per-server **Admin-Server** toolkit on a fresh hosting account so config drift detection, MD5 integrity checks, disk/inode alerts, PHP error-log scanning, domain inventory, log rotation, and alert channels (`ops` · `deploys` · `backups`) are defined **once** for every app on that account.

:::note[For beginners and agents]
**Gate — done when** — `~/Admin-Server/scripts/status.sh` exits `0` and reports the expected identity, the log freshness probe reports no `STALE` rows, `monitored-paths.conf` includes `~/.ssh/authorized_keys` plus every app domain path being reused, and one synthetic alert arrives through an `ops` webhook with the correct env prefix: **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`**. Deploy, backup, and heartbeat slots are either configured or explicitly waived in `Zaj-PROJECT.md`; blank slots are no-ops, not proof that alerting works.

**Once per server, not per project.** Re-run only when you add a **new** hosting account. If scripts already exist, detect-and-skip — verify, do not reinstall.

**⏱ ~2 min** (verify) · **~15–25 min** (first install) · **🔀** all work over SSH on the server; **👤** Hostinger API/panel authorization + webhook paste in `nano` on the server.
:::

---

This is the **account-scoped server-readiness playbook** before [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) reaches deployment. Conceptual companion: [Three-tier admin (handbook)](/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/).

<StageFlow
  title="Once per account, then every app"
  stages={[
    { label: 'This account', sub: 'Admin-Server readiness', tone: 'core' },
    { label: 'App #1', sub: 'setup-new', tone: 'good' },
    { label: 'App #N', sub: 'reuse server tier', tone: 'muted' },
  ]}
/>

```mermaid
flowchart LR
  A["New hosting account"] --> B["Server readiness · this playbook"]
  B --> C["setup-new · app 1"]
  B --> D["setup-new · app N"]
```

## Operating rules

Every task in this phase follows four operating rules:

| Rule | Meaning |
| --- | --- |
| **Runs on the server** | SSH into `~/Admin-Server/` on the hosting account — zero toolkit binaries on your laptop |
| **Secrets stay server-side** | No webhook URL or SA token in laptop argv or agent chat — see [Secrets discipline](#secrets-discipline) |
| **Idempotent** | Re-run safe: `git pull`-friendly; baselines non-destructive; cron lines detected before duplicate add |
| **Secret source of truth** | Webhooks and heartbeat URLs are created/stored first in the shared infrastructure 1Password vault recorded in `Zaj-PROJECT.md` (default example: `General-Dev`); runtime copies live only in gitignored `server.env` at `chmod 600` |

:::danger[Presence is not liveness]
`~/Admin-Server/scripts/status.sh` can exist and still be stale if Hostinger cron jobs stopped weeks ago. A reusable Admin-Server must pass both checks: `status.sh` exits `0` **and** every expected log file is fresh within twice its cron interval. A `STALE` row blocks reuse until the cron is fixed and the script runs again.
:::

:::note[Pairing with laptop setup]
[Machine setup](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/) configures **your laptop** (`gh`, MCP, `op`). **This playbook configures each hosting account.** The two tracks are independent — run them in either order — but **both must complete before [Deploy pipeline](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/)** registers webhooks through Admin-Server's `deploys` channel. After this playbook, record the SSH alias and `Admin-Hostinger-<account>` repo name in the project's gitignored `CLAUDE.local.md`.
:::

### Tasks at a glance

| # | Task | Priority | Type |
| --- | --- | --- | --- |
| 0.1 | Clone Admin-Server toolkit + initial repo setup | MUST | CLI (SSH) |
| 0.2 | Download `op` 1Password CLI *(no root)* | MUST after P9C-1 | CLI |
| 0.3 | Bootstrap `config/server.env` from template | MUST | 👤 on server (`nano`) |
| 0.4 | Make scripts executable + `chmod 600` on `server.env` | MUST | CLI |
| 0.5 | Generate initial MD5 baseline | MUST | CLI |
| 0.6 | Run `status.sh` smoke test | MUST | CLI |
| 0.7 | Fire one synthetic alert through `ops` channel | MUST | CLI |
| 0.8 | Register Hostinger cron entries (6 lines, 5-field syntax) | MUST | API or 👤 hPanel UI |
| 0.9 | Discover server runtime paths | MUST | CLI |
| 0.10 | First commit + push to per-server private repo | MUST | CLI |
| 0.11 | Document server in `CLAUDE.local.md` | SHOULD | Manual |

:::caution[Agents — do not invent Admin-Server layout]
If task text references scripts that are missing on disk, follow the **Admin-Server cross-phase proposal** in `_Sources/laravel/codecanyon/server-setup/admin-server-cross-phase-integration-proposal.md` (§ "Initial server setup checklist") — do not flesh out paths from training-data guesses. Interim flow uses webhook URLs in `server.env`; P9C-1 replaces that with 1Password Service Account fetch.
:::

## Before you start

| Prerequisite | Verify |
| --- | --- |
| SSH public-key auth to the account | `ssh <SSH_ALIAS> 'echo ok'` — no password prompt |
| Private GitHub repo `Admin-Hostinger-<account>` | Empty repo OK for first push |
| Discord or Slack ops channel | Ops webhook ready for `#server-alerts` or the project's equivalent; configure only through the secret-safe flow below |
| Shared infrastructure 1Password vault | Record the actual vault name in `Zaj-PROJECT.md`; `General-Dev` is the default example, not a fixed requirement |
| Heartbeat provider decision | MonSpark, Healthchecks.io, Better Stack, Cronitor, UptimeRobot heartbeats, or `N/A` with reason |

## Detect and skip

Run before any install work:

```bash
   ssh <SSH_ALIAS> '
     if [ -x ~/Admin-Server/scripts/status.sh ]; then
       echo "Admin-Server present — run Verify existing next"
       ~/Admin-Server/scripts/status.sh
     else
       ls ~/Admin-Server/scripts/*.sh 2>/dev/null | head -10
     fi
   '
```

| Output | Action |
| --- | --- |
| `status.sh` or scripts listed | Jump to [Verify existing](#verify-existing) — skip setup steps 0.1–0.5 only after liveness passes |
| No such file | Continue with the [setup tasks](#tasks) |
| Scripts but no `lib/init.sh` or no `config/server.env` | Legacy layout — run [Migrate legacy installs to v2](#migrate-legacy-installs-to-v2) before cron or app reuse |

---

## Migrate legacy installs to v2

Run this branch when `~/Admin-Server/` exists but uses the older layout (`config/webhooks.conf`, missing `config/server.env`, missing `lib/init.sh`, or scripts that do not write the expected logs). Migration is not a pass by itself; after it, run [Verify existing](#verify-existing).

<Steps>

1. **Normalize the config layout without deleting legacy files.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   mkdir -p config logs baselines
   if [ ! -f config/server.env ]; then
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     echo "Created config/server.env from example; edit it before alerting checks."
   fi
   [ -f config/webhooks.conf ] && echo "Legacy config/webhooks.conf kept as read-only fallback."
   test -d lib || echo "Missing lib/ — pull the Admin-Server v2 repo before continuing."
   git status --short
   REMOTE
   ```

   Expected: `config/server.env` exists at `chmod 600`; legacy `webhooks.conf` is not deleted; missing `lib/` is treated as a blocker until the v2 repo is pulled.

2. **Complete the v2 gates.** Edit `server.env` with the slot matrix in step 0.3, register absolute-path cron rows in step 0.8, regenerate the baseline, then run [Verify existing](#verify-existing). A migrated server does not become deploy-ready until the freshness probe has no `STALE` rows.

</Steps>

## Tasks

Verification-first flow: **Clone → op CLI (P9C-1) → `server.env` → baseline → status + alert → cron liveness → runtime discovery → commit/push**.

### 0.1 · Clone Admin-Server toolkit

<Steps>

1. **Clone the per-server private repo** into `~/Admin-Server/`.

   ```bash
   ssh <SSH_ALIAS> '
     git clone git@github.com-<GITHUB_USER>:<GITHUB_USER>/Admin-Hostinger-<account>.git ~/Admin-Server
     cd ~/Admin-Server && git remote -v
   '
   # Expected: origin → your Admin-Hostinger-<account> repo
   ```

2. **If the directory already exists**, update instead of re-cloning.

   ```bash
   ssh <SSH_ALIAS> 'cd ~/Admin-Server && git fetch && git pull'
   ```

</Steps>

### 0.2 · `op` CLI *(deferred — P9C-1)*

Step **0.2** (download `op` 1Password CLI, no root) is **MUST after P9C-1**, not part of the interim bootstrap. For forward compatibility only, add an empty placeholder when editing `server.env` in step 0.3:

```bash
OP_SERVICE_ACCOUNT_TOKEN=""
```

Do not run `op signin` from an agent session.

### 0.3 · Bootstrap `config/server.env`

<Steps>

1. **Create `server.env` from the template** on the server only.

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

2. **Set identity and at least one ops webhook** from the shared infrastructure vault (paste URL in `nano` on server — never into chat).

   Minimum alerting-ready fields: `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` (`staging` \| `production`), plus `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS`. The source copy lives in 1Password, usually `op://General-Dev/...` unless `Zaj-PROJECT.md` names a different shared infrastructure vault.

</Steps>

:::danger[Installed ≠ alerting works]
`server.env` is the Admin-Server v2 runtime source of truth. A green `status.sh` proves scripts and cron freshness; it does **not** prove Slack, Discord, or external heartbeat destinations are wired. Empty alert or heartbeat values silently no-op. Do not mark the account alerting-ready until the synthetic `ops` alert reaches the expected channel and each adopted heartbeat monitor shows a fresh ping.
:::

| Slot | Variables | Required? | Behavior when blank |
| --- | --- | --- | --- |
| Server identity | `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` | Required | `status.sh` cannot prove the account identity |
| Ops alerts | `DISCORD_WEBHOOK_OPS`, `SLACK_WEBHOOK_OPS` | Required for alerting-ready | Monitoring alerts log locally only; this playbook's alert gate cannot pass |
| Deploy notifications | `DISCORD_WEBHOOK_DEPLOYS`, `SLACK_WEBHOOK_DEPLOYS` | Required when deploy notifications are enabled | Deployer Section J logs "notification skipped" and continues |
| Backup notifications | `DISCORD_WEBHOOK_BACKUPS`, `SLACK_WEBHOOK_BACKUPS` | Required when backup alerting is enabled | Backup alerts no-op or fall back to ops depending on the script |
| Legacy/default webhook | `WEBHOOK_URL` | Legacy fallback only | Current v2 scripts should prefer the channel-specific vars above |
| External heartbeat pings | `HEARTBEAT_SNAPSHOT`, `HEARTBEAT_INTEGRITY`, `HEARTBEAT_RESOURCE`, `HEARTBEAT_ERRORLOG`, `HEARTBEAT_INVENTORY` | Required when external heartbeat monitoring is claimed | Cron still runs locally, but MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot will not page on missed runs |
| Future 1Password fetch | `OP_SERVICE_ACCOUNT_TOKEN` | Empty until service-account hardening | `server.env` remains the runtime copy; source values stay in the shared infra vault |

### Wire alerting destinations

Alert channels are part of the server setup, not a later nice-to-have. Use the channel names below as the default map, then record the actual workspace/channel names in `Zaj-PROJECT.md`.

If an agent is driving Discord, Slack, or MonSpark through the operator's logged-in browser, use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/): click by accessibility-tree element refs, not screenshot coordinates; let the human own login and secret-copy moments; move copied URLs through clipboard → stdin so webhook and heartbeat URLs never print in chat, terminal output, or process lists.

| Route | Common destination | Variables |
| --- | --- | --- |
| Ops | `#server-alerts` | `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS` |
| Deploys | `#deployments` | `DISCORD_WEBHOOK_DEPLOYS` or `SLACK_WEBHOOK_DEPLOYS` |
| Backups | ops or backup channel | `DISCORD_WEBHOOK_BACKUPS` or `SLACK_WEBHOOK_BACKUPS` |
| App alerts | `#app-alerts` | App/Sentry/MonSpark routing, not Admin-Server deploy vars |

<Steps>

1. **Create or reuse provider webhooks** in the right workspace.

   - Discord: right-click channel → **Edit Channel** → **Integrations** → **Create Webhook** → rename → **Save** → **Copy URL**.
   - Slack: `api.slack.com/apps` → **Incoming Webhooks** → **Add to Workspace** → channel → **Copy**.
   - MonSpark heartbeats: **Cron Job** → **Create Monitor** → name/interval/grace → **Copy heartbeat URL**.
   - If the operator already has the right channel and webhook, reuse it; do not create duplicates.

2. **Store every URL in 1Password before it touches the server.**

   ```md
   Shared infra vault: <actual-vault-name>  # default example: General-Dev
   op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS
   op://<vault>/Admin-Server/SLACK_WEBHOOK_DEPLOYS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_DEPLOYS
   ```

3. **Smoke-test endpoints without printing secrets.**

   ```bash
   DISCORD_URL="$(op read 'op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS')"
   curl -fsS -o /dev/null -w '%{http_code}\n' "$DISCORD_URL"
   unset DISCORD_URL
   # Expected: 200 for Discord webhook GET metadata

   SLACK_URL="$(op read 'op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS')"
   printf '{"text":"Admin-Server webhook smoke test"}' \
     | curl -fsS -X POST -H 'Content-type: application/json' --data @- "$SLACK_URL"
   unset SLACK_URL
   # Expected: ok
   ```

   If a provider does not support a harmless preflight for that URL, skip the endpoint probe and rely on the real `send_alert`/`alert-helper` test after wiring.

4. **Paste into `config/server.env` through an interactive editor or secure clipboard bridge.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

   Never echo webhook URLs into terminal logs, agent chat, README files, screenshots, or commits.

5. **Verify with the shipped alert helper.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     if [ -x scripts/send_alert.sh ]; then
       bash scripts/send_alert.sh ops INFO "Admin-Server alerting smoke test for $(hostname)"
     else
       bash scripts/alert-helper.sh INFO "Admin-Server alerting smoke test for $(hostname)" ops
     fi
   '
   # Expected: exit 0 and the ops channel receives the message with the server env prefix.
   ```

</Steps>

### 0.4 · Executable scripts + `server.env` permissions

<Steps>

1. **chmod scripts and confirm `server.env` stays private.**

   ```bash
   ssh <SSH_ALIAS> '
     chmod +x ~/Admin-Server/scripts/*.sh
     chmod 600 ~/Admin-Server/config/server.env
     ls -l ~/Admin-Server/scripts/status.sh ~/Admin-Server/config/server.env
   '
   # Expected: scripts -rwx; server.env -rw------- 
   ```

</Steps>

### 0.5 · Generate initial MD5 baseline

<Steps>

1. **Generate and commit the integrity baseline.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     conf="config/monitored-paths.conf"
     touch "$conf"
     grep -Fxq "$HOME/.ssh/authorized_keys" "$conf" 2>/dev/null || printf "%s\n" "$HOME/.ssh/authorized_keys" >> "$conf"
     ~/Admin-Server/scripts/generate-baseline.sh
     git add "$conf" baselines/checksums.md5
     git diff --cached --quiet || git commit -m "Initial integrity baseline"
   '
   # Expected: checksums.md5 with server dotfiles and ~/.ssh/authorized_keys
   ```

</Steps>

### 0.6 · Run `status.sh` smoke test

<Steps>

1. **Run the health snapshot** — this is the **verify** step in the eight-step flow.

   ```bash
   ssh <SSH_ALIAS> '~/Admin-Server/scripts/status.sh'
   ```

	   Expected: clean `SERVER_LABEL` / `SERVER_ENV`; baseline ✅; webhook slots show ✅/❌ (at least one ✅ before you leave this playbook); **cron schedule printed** — use that output for the cron step.

</Steps>

### 0.7 · Fire one synthetic alert (`ops` channel)

<Steps>

1. **Send a test alert** through the ops channel.

   ```bash
   ssh <SSH_ALIAS> '
     ~/Admin-Server/scripts/alert-helper.sh INFO "Server-readiness smoke test" "Hello from $(hostname)" ops
   '
   ```

   **Expected:** Discord/Slack message with **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`** prefix.

</Steps>

### 0.8 · Register six Hostinger cron entries

Hostinger shared hosting often has **no** SSH `crontab` CLI. Use the Hostinger REST API when you have the account token; otherwise use hPanel → Advanced → Cron Jobs. Use SSH `crontab` only on hosts where `command -v crontab` succeeds.

:::caution[Hostinger cron commands are not shell scripts]
The Hostinger API/panel stores a command, but it does not safely expand `$HOME` or run shell operators for you. Use an absolute path such as `/home/<user>/Admin-Server/scripts/integrity-check.sh`, and keep redirects/pipes inside wrapper scripts if a command needs them.
:::

| Cron job | Typical script | Watches |
| --- | --- | --- |
| Config snapshot | `snapshot-config.sh` | Tracked config drift |
| MD5 integrity | `integrity-check.sh` | Baseline mutations |
| Disk / inode | `resource-check.sh` | Space and inode exhaustion |
| PHP error log | `error-log-check.sh` | New PHP errors across domains |
| Domain inventory | `domain-inventory.sh` | Apps/domains on account |
| Log rotation | `rotate-logs.sh` | Log volume |

<Steps>

1. **Resolve the absolute Admin-Server path** before creating any cron row.

   ```bash
   ssh <SSH_ALIAS> 'printf "ADMIN_SERVER=%s\n" "$HOME/Admin-Server"'
   # Expected: ADMIN_SERVER=/home/<user>/Admin-Server
   ```

2. **Copy cron expressions from `status.sh` output** (step 0.6) — do not guess schedules.

3. **Create or verify the six cron rows** with API GET-before-POST when available. Match the absolute command exactly.

   ```bash
   # Example row payload shape; repeat for each script from the table above.
   # Do not include redirects, pipes, or $HOME in command.
   command="bash /home/<user>/Admin-Server/scripts/snapshot-config.sh"
   ```

   If the API is not available, add the same absolute commands in hPanel and verify **five-field** syntax (`min hour dom mon dow`). A UI preset is not enough; inspect the saved row.

4. **Confirm log files update** after the first interval with the freshness probe.

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then
       echo "❌ STALE $label — missing $path"; exit 1
     fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   ```

   Expected: every row prints `✅ fresh`; any `❌ STALE` row means the cron is not alive enough for app deploys.

</Steps>

### External heartbeat wiring *(MonSpark, Healthchecks, Better Stack, Cronitor, UptimeRobot)*

External heartbeat monitors are layered on top of the local cron/log freshness gate. They are useful, but they are not a substitute for fresh Admin-Server logs. If the operator already pays for MonSpark, Better Stack, Cronitor, or UptimeRobot heartbeat monitors, use that tool here instead of signing up for a new Healthchecks.io account.

| Script | Heartbeat slot | Provider examples |
| --- | --- | --- |
| `snapshot-config.sh` | `HEARTBEAT_SNAPSHOT` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `integrity-check.sh` | `HEARTBEAT_INTEGRITY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `resource-check.sh` | `HEARTBEAT_RESOURCE` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `error-log-check.sh` | `HEARTBEAT_ERRORLOG` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `domain-inventory.sh` | `HEARTBEAT_INVENTORY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |

If a slot is blank, that script should still run locally but will not ping the external heartbeat provider. If you claim external heartbeat monitoring is configured, paste the heartbeat URLs into `config/server.env`, run the matching script once, and confirm the provider dashboard receives the ping. Leave blank slots explicitly documented as `N/A — no external heartbeat configured`.

For MonSpark specifically, create one **Cron Job** monitor per Admin-Server script and paste its URL into the matching `HEARTBEAT_*` slot. The [MonSpark monitoring guide](/tech-stack/laravel/codecanyon/learn/guides/monspark-monitoring/) covers the full provider setup and optional Laravel `MONSPARK_CRON_URL` scheduler heartbeat.

### 0.9 · Discover server runtime paths

<Steps>

1. **Record the server runtime paths the app deploys will consume.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   {
     echo "# Generated by setup-shared-hosting; update when hPanel PHP/Node changes."
     echo "PHP_LOGIN_SHELL=$(command -v php || true)"
     for phpbin in /opt/alt/php84/usr/bin/php /opt/alt/php83/usr/bin/php /opt/alt/php82/usr/bin/php /usr/local/bin/php /usr/bin/php; do
       [ -x "$phpbin" ] && printf 'PHP_CANDIDATE=%s # %s\n' "$phpbin" "$("$phpbin" -r 'echo PHP_VERSION;' 2>/dev/null || true)"
     done
     echo "COMPOSER_BIN=$(command -v composer || true)"
     echo "NODE_BIN=$(command -v node || true)"
     echo "NPM_BIN=$(command -v npm || true)"
   } > config/server-environment.conf
   cat config/server-environment.conf
   git add config/server-environment.conf
   git diff --cached --quiet || git commit -m "Record server environment paths"
   REMOTE
   ```

   Expected: `config/server-environment.conf` is committed and shows the login-shell PHP separately from versioned PHP candidates. Later deploy pages still confirm the domain's selected web/CLI PHP before pinning Composer.

</Steps>

### 0.10 · First commit + push

<Steps>

1. **Push the Admin-Server repo** (baseline + monitored paths + committed config such as `server-environment.conf`).

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     git status
     git push
   '
   ```

</Steps>

### 0.11 · Document the server *(SHOULD)*

Record in the project's **`CLAUDE.local.md`** (or equivalent local-only notes): SSH alias, `Admin-Hostinger-<account>` repo name, last baseline date, last webhook rotation — not in git-tracked secrets.

---

## Verify existing

When detect-and-skip found scripts already installed:

```bash
ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE
```

Fix only failed checks (missing baseline → 0.5; stale logs → 0.8; unset webhooks → 0.3 + 0.7). Then return to your app playbook.

If this verification is happening for a specific app domain, add that domain path to the integrity baseline before you return:

```bash
APP_DOMAIN="<domain.example.com>"
ssh <SSH_ALIAS> "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
APP_DOMAIN="${APP_DOMAIN:?set APP_DOMAIN before running}"
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the domain path; baseline regenerated
```

## Idempotent re-run

| Concern | On second run |
| --- | --- |
| Repo | `git fetch && git pull` — no re-clone |
| Cron | Detected before add — no duplicates |
| Baseline | Regeneration non-destructive |
| Health | `status.sh` + the log freshness probe |

## Secrets discipline

- Webhook URLs are **credentials** — live only in 1Password and gitignored `server.env`; never in README files, examples, commits, screenshots, or chat.
- A committed webhook URL is compromised. Delete/recreate the webhook, then update 1Password and `server.env`; editing nearby config is not recovery.
- Before committing Admin-Server docs/config examples, run `rg -n 'discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9._-]+' .` and confirm there are no tracked Discord webhook URLs.
- **`server.env`**: `chmod 600`, gitignored — interim SoT for `ops` / `deploys` / `backups`.  
- Prefer **server-to-server** copy or **clipboard bridge** at keyboard — never through agent chat.  
- **P9C-1 (future):** 1Password SA fetch replaces plaintext URLs — see [Hardening](#hardening-serverenv).

## Hardening `server.env`

| Weakness | Interim | After P9C-1 |
| --- | --- | --- |
| Plaintext webhooks on disk | `chmod 600` + gitignore | SA fetch at runtime |
| No audit trail | Rotation log in monitoring state | 1Password activity log |
| Per-server manual rotation | Operator checklist | Rotate vault once; servers pull fresh |

Later hardening: move Discord/Slack webhook URLs out of plaintext `server.env` into a scoped read-only 1Password service-account fetch that fails closed. This is post-launch Admin-Server ops work, not a setup-new Phase 9 launch gate.

P9C-1 unblocks after the CodeCanyon payments setup proves `op` on Hostinger CloudLinux.

---

## Checklist

Verification checklist:

- [ ] SSH alias works passwordlessly from laptop
- [ ] Server GitHub auth: `ssh -T git@github.com-<GITHUB_USER>` succeeds
- [ ] `~/Admin-Server/` present; `git remote -v` correct
- [ ] All monitoring scripts executable (`-rwx`)
- [ ] `config/server.env` exists at `chmod 600`, gitignored
- [ ] Six cron entries installed through Hostinger API/hPanel or SSH `crontab` when available; each row uses `bash /home/<user>/Admin-Server/scripts/<script>.sh` with no `$HOME`, pipes, or redirects
- [ ] Admin-Server logs are fresh within each cron interval ×2; no `STALE` rows
- [ ] `baselines/checksums.md5` exists with ≥4 entries
- [ ] Test alert received with `[STAGING] 🟡` or `[PRODUCTION] 🔴` prefix
- [ ] Adopted external heartbeat slots show fresh provider pings, or each blank slot is recorded as `N/A` with reason
- [ ] `config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's domain path before reuse
- [ ] `config/server-environment.conf` committed with PHP/Node/Composer path candidates
- [ ] Server documented in `CLAUDE.local.md` *(step 0.11)*

## What's next

<CardGrid>
  <LinkCard title="Machine setup" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/" description="Once per laptop — gh, MCP, op — pairs with this server gate." />
  <LinkCard title="CodeCanyon setup-new" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/" description="Per-app playbook — run after this account gate passes." />
  <LinkCard title="Three-tier admin model" href="/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/" description="Admin-Local · Admin-Domain · Admin-Server + cascade resolver." />
  <LinkCard title="Deploy pipeline · step 1" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/01-deployer/" description="Assumes Admin-Server paths resolve for deploys/backups webhooks." />
</CardGrid>

### Maintainer note

Source archives and intake ledgers stay out of reader-facing playbooks. The workflow above is the published server-readiness path.

:::next[Next: start a CodeCanyon project]
When the gate passes, continue with [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) — Phase 1 workspace setup on your laptop.
:::

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 — bootstrap the per-server Admin-Server toolkit on a fresh hosting account so config drift detection, MD5 integrity checks, disk/inode alerts, PHP error-log scanning, domain inventory, log rotation, and alert channels (ops · deploys · backups) are defined once for every app on that account.

Gate — done when — ~/Admin-Server/scripts/status.sh exits 0 and reports the expected identity, the log freshness probe reports no STALE rows, monitored-paths.conf includes ~/.ssh/authorized_keys plus every app domain path being reused, and one synthetic alert arrives through an ops webhook with the correct env prefix: [STAGING] 🟡 or [PRODUCTION] 🔴. Deploy, backup, and heartbeat slots are either configured or explicitly waived in Zaj-PROJECT.md; blank slots are no-ops, not proof that alerting works.

Once per server, not per project. Re-run only when you add a new hosting account. If scripts already exist, detect-and-skip — verify, do not reinstall.

⏱ ~2 min (verify) · ~15–25 min (first install) · 🔀 all work over SSH on the server; 👤 Hostinger API/panel authorization + webhook paste in nano on the server.

This is the account-scoped server-readiness playbook before CodeCanyon setup-new reaches deployment. Conceptual companion: Three-tier admin (handbook).

Once per account, then every app

flowchart LR
  A["New hosting account"] --> B["Server readiness · this playbook"]
  B --> C["setup-new · app 1"]
  B --> D["setup-new · app N"]

Operating rules

Every task in this phase follows four operating rules:

Rule	Meaning
Runs on the server	SSH into `~/Admin-Server/` on the hosting account — zero toolkit binaries on your laptop
Secrets stay server-side	No webhook URL or SA token in laptop argv or agent chat — see Secrets discipline
Idempotent	Re-run safe: `git pull`-friendly; baselines non-destructive; cron lines detected before duplicate add
Secret source of truth	Webhooks and heartbeat URLs are created/stored first in the shared infrastructure 1Password vault recorded in `Zaj-PROJECT.md` (default example: `General-Dev`); runtime copies live only in gitignored `server.env` at `chmod 600`

Tasks at a glance

#	Task	Priority	Type
0.1	Clone Admin-Server toolkit + initial repo setup	MUST	CLI (SSH)
0.2	Download `op` 1Password CLI (no root)	MUST after P9C-1	CLI
0.3	Bootstrap `config/server.env` from template	MUST	👤 on server (`nano`)
0.4	Make scripts executable + `chmod 600` on `server.env`	MUST	CLI
0.5	Generate initial MD5 baseline	MUST	CLI
0.6	Run `status.sh` smoke test	MUST	CLI
0.7	Fire one synthetic alert through `ops` channel	MUST	CLI
0.8	Register Hostinger cron entries (6 lines, 5-field syntax)	MUST	API or 👤 hPanel UI
0.9	Discover server runtime paths	MUST	CLI
0.10	First commit + push to per-server private repo	MUST	CLI
0.11	Document server in `CLAUDE.local.md`	SHOULD	Manual

Before you start

Prerequisite	Verify
SSH public-key auth to the account	`ssh <SSH_ALIAS> 'echo ok'` — no password prompt
Private GitHub repo `Admin-Hostinger-<account>`	Empty repo OK for first push
Discord or Slack ops channel	Ops webhook ready for `#server-alerts` or the project’s equivalent; configure only through the secret-safe flow below
Shared infrastructure 1Password vault	Record the actual vault name in `Zaj-PROJECT.md`; `General-Dev` is the default example, not a fixed requirement
Heartbeat provider decision	MonSpark, Healthchecks.io, Better Stack, Cronitor, UptimeRobot heartbeats, or `N/A` with reason

Detect and skip

Run before any install work:

   ssh <SSH_ALIAS> '
     if [ -x ~/Admin-Server/scripts/status.sh ]; then
       echo "Admin-Server present — run Verify existing next"
       ~/Admin-Server/scripts/status.sh
     else
       ls ~/Admin-Server/scripts/*.sh 2>/dev/null | head -10
     fi
   '

Output	Action
`status.sh` or scripts listed	Jump to Verify existing — skip setup steps 0.1–0.5 only after liveness passes
No such file	Continue with the setup tasks
Scripts but no `lib/init.sh` or no `config/server.env`	Legacy layout — run Migrate legacy installs to v2 before cron or app reuse

Migrate legacy installs to v2

Run this branch when ~/Admin-Server/ exists but uses the older layout (config/webhooks.conf, missing config/server.env, missing lib/init.sh, or scripts that do not write the expected logs). Migration is not a pass by itself; after it, run Verify existing.

Normalize the config layout without deleting legacy files.

ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
mkdir -p config logs baselines
if [ ! -f config/server.env ]; then
  cp config/server.env.example config/server.env
  chmod 600 config/server.env
  echo "Created config/server.env from example; edit it before alerting checks."
fi
[ -f config/webhooks.conf ] && echo "Legacy config/webhooks.conf kept as read-only fallback."
test -d lib || echo "Missing lib/ — pull the Admin-Server v2 repo before continuing."
git status --short
REMOTE

Expected: config/server.env exists at chmod 600; legacy webhooks.conf is not deleted; missing lib/ is treated as a blocker until the v2 repo is pulled.

Complete the v2 gates. Edit server.env with the slot matrix in step 0.3, register absolute-path cron rows in step 0.8, regenerate the baseline, then run Verify existing. A migrated server does not become deploy-ready until the freshness probe has no STALE rows.

Tasks

Verification-first flow: Clone → op CLI (P9C-1) → server.env → baseline → status + alert → cron liveness → runtime discovery → commit/push.

0.1 · Clone Admin-Server toolkit

Clone the per-server private repo into ~/Admin-Server/.

ssh <SSH_ALIAS> '
  git clone git@github.com-<GITHUB_USER>:<GITHUB_USER>/Admin-Hostinger-<account>.git ~/Admin-Server
  cd ~/Admin-Server && git remote -v
'
# Expected: origin → your Admin-Hostinger-<account> repo

If the directory already exists, update instead of re-cloning.
Terminal window
```
ssh <SSH_ALIAS> 'cd ~/Admin-Server && git fetch && git pull'
```

0.2 · `op` CLI (deferred — P9C-1)

Step 0.2 (download op 1Password CLI, no root) is MUST after P9C-1, not part of the interim bootstrap. For forward compatibility only, add an empty placeholder when editing server.env in step 0.3:

OP_SERVICE_ACCOUNT_TOKEN=""

Do not run op signin from an agent session.

0.3 · Bootstrap `config/server.env`

Create server.env from the template on the server only.

ssh <SSH_ALIAS> '
  cd ~/Admin-Server
  cp config/server.env.example config/server.env
  chmod 600 config/server.env
  nano config/server.env
'

Set identity and at least one ops webhook from the shared infrastructure vault (paste URL in nano on server — never into chat).

Minimum alerting-ready fields: SERVER_NAME, SERVER_LABEL, SERVER_ENV (staging | production), plus DISCORD_WEBHOOK_OPS or SLACK_WEBHOOK_OPS. The source copy lives in 1Password, usually op://General-Dev/... unless Zaj-PROJECT.md names a different shared infrastructure vault.

Slot	Variables	Required?	Behavior when blank
Server identity	`SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV`	Required	`status.sh` cannot prove the account identity
Ops alerts	`DISCORD_WEBHOOK_OPS`, `SLACK_WEBHOOK_OPS`	Required for alerting-ready	Monitoring alerts log locally only; this playbook’s alert gate cannot pass
Deploy notifications	`DISCORD_WEBHOOK_DEPLOYS`, `SLACK_WEBHOOK_DEPLOYS`	Required when deploy notifications are enabled	Deployer Section J logs “notification skipped” and continues
Backup notifications	`DISCORD_WEBHOOK_BACKUPS`, `SLACK_WEBHOOK_BACKUPS`	Required when backup alerting is enabled	Backup alerts no-op or fall back to ops depending on the script
Legacy/default webhook	`WEBHOOK_URL`	Legacy fallback only	Current v2 scripts should prefer the channel-specific vars above
External heartbeat pings	`HEARTBEAT_SNAPSHOT`, `HEARTBEAT_INTEGRITY`, `HEARTBEAT_RESOURCE`, `HEARTBEAT_ERRORLOG`, `HEARTBEAT_INVENTORY`	Required when external heartbeat monitoring is claimed	Cron still runs locally, but MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot will not page on missed runs
Future 1Password fetch	`OP_SERVICE_ACCOUNT_TOKEN`	Empty until service-account hardening	`server.env` remains the runtime copy; source values stay in the shared infra vault

Wire alerting destinations

Alert channels are part of the server setup, not a later nice-to-have. Use the channel names below as the default map, then record the actual workspace/channel names in Zaj-PROJECT.md.

If an agent is driving Discord, Slack, or MonSpark through the operator’s logged-in browser, use the vendor console automation guide: click by accessibility-tree element refs, not screenshot coordinates; let the human own login and secret-copy moments; move copied URLs through clipboard → stdin so webhook and heartbeat URLs never print in chat, terminal output, or process lists.

Route	Common destination	Variables
Ops	`#server-alerts`	`DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS`
Deploys	`#deployments`	`DISCORD_WEBHOOK_DEPLOYS` or `SLACK_WEBHOOK_DEPLOYS`
Backups	ops or backup channel	`DISCORD_WEBHOOK_BACKUPS` or `SLACK_WEBHOOK_BACKUPS`
App alerts	`#app-alerts`	App/Sentry/MonSpark routing, not Admin-Server deploy vars

Create or reuse provider webhooks in the right workspace.
- Discord: right-click channel → Edit Channel → Integrations → Create Webhook → rename → Save → Copy URL.
- Slack: api.slack.com/apps → Incoming Webhooks → Add to Workspace → channel → Copy.
- MonSpark heartbeats: Cron Job → Create Monitor → name/interval/grace → Copy heartbeat URL.
- If the operator already has the right channel and webhook, reuse it; do not create duplicates.

Store every URL in 1Password before it touches the server.

Shared infra vault: <actual-vault-name>  # default example: General-Dev
op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS
op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS
op://<vault>/Admin-Server/SLACK_WEBHOOK_DEPLOYS
op://<vault>/Admin-Server/DISCORD_WEBHOOK_DEPLOYS

Smoke-test endpoints without printing secrets.

DISCORD_URL="$(op read 'op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS')"
curl -fsS -o /dev/null -w '%{http_code}\n' "$DISCORD_URL"
unset DISCORD_URL
# Expected: 200 for Discord webhook GET metadata

SLACK_URL="$(op read 'op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS')"
printf '{"text":"Admin-Server webhook smoke test"}' \
  | curl -fsS -X POST -H 'Content-type: application/json' --data @- "$SLACK_URL"
unset SLACK_URL
# Expected: ok

If a provider does not support a harmless preflight for that URL, skip the endpoint probe and rely on the real send_alert/alert-helper test after wiring.

Paste into config/server.env through an interactive editor or secure clipboard bridge.
Terminal window
```
ssh <SSH_ALIAS> '
  cd ~/Admin-Server
  chmod 600 config/server.env
  nano config/server.env
'
```
Never echo webhook URLs into terminal logs, agent chat, README files, screenshots, or commits.

Verify with the shipped alert helper.

ssh <SSH_ALIAS> '
  cd ~/Admin-Server
  if [ -x scripts/send_alert.sh ]; then
    bash scripts/send_alert.sh ops INFO "Admin-Server alerting smoke test for $(hostname)"
  else
    bash scripts/alert-helper.sh INFO "Admin-Server alerting smoke test for $(hostname)" ops
  fi
'
# Expected: exit 0 and the ops channel receives the message with the server env prefix.

0.4 · Executable scripts + `server.env` permissions

chmod scripts and confirm server.env stays private.

ssh <SSH_ALIAS> '
  chmod +x ~/Admin-Server/scripts/*.sh
  chmod 600 ~/Admin-Server/config/server.env
  ls -l ~/Admin-Server/scripts/status.sh ~/Admin-Server/config/server.env
'
# Expected: scripts -rwx; server.env -rw-------

0.5 · Generate initial MD5 baseline

Generate and commit the integrity baseline.

ssh <SSH_ALIAS> '
  cd ~/Admin-Server
  conf="config/monitored-paths.conf"
  touch "$conf"
  grep -Fxq "$HOME/.ssh/authorized_keys" "$conf" 2>/dev/null || printf "%s\n" "$HOME/.ssh/authorized_keys" >> "$conf"
  ~/Admin-Server/scripts/generate-baseline.sh
  git add "$conf" baselines/checksums.md5
  git diff --cached --quiet || git commit -m "Initial integrity baseline"
'
# Expected: checksums.md5 with server dotfiles and ~/.ssh/authorized_keys

0.6 · Run `status.sh` smoke test

Run the health snapshot — this is the verify step in the eight-step flow.
Terminal window
```
ssh <SSH_ALIAS> '~/Admin-Server/scripts/status.sh'
```
Expected: clean SERVER_LABEL / SERVER_ENV; baseline ✅; webhook slots show ✅/❌ (at least one ✅ before you leave this playbook); cron schedule printed — use that output for the cron step.

0.7 · Fire one synthetic alert (`ops` channel)

Send a test alert through the ops channel.
Terminal window
```
ssh <SSH_ALIAS> '
  ~/Admin-Server/scripts/alert-helper.sh INFO "Server-readiness smoke test" "Hello from $(hostname)" ops
'
```
Expected: Discord/Slack message with [STAGING] 🟡 or [PRODUCTION] 🔴 prefix.

0.8 · Register six Hostinger cron entries

Hostinger shared hosting often has no SSH crontab CLI. Use the Hostinger REST API when you have the account token; otherwise use hPanel → Advanced → Cron Jobs. Use SSH crontab only on hosts where command -v crontab succeeds.

Cron job	Typical script	Watches
Config snapshot	`snapshot-config.sh`	Tracked config drift
MD5 integrity	`integrity-check.sh`	Baseline mutations
Disk / inode	`resource-check.sh`	Space and inode exhaustion
PHP error log	`error-log-check.sh`	New PHP errors across domains
Domain inventory	`domain-inventory.sh`	Apps/domains on account
Log rotation	`rotate-logs.sh`	Log volume

Resolve the absolute Admin-Server path before creating any cron row.

ssh <SSH_ALIAS> 'printf "ADMIN_SERVER=%s\n" "$HOME/Admin-Server"'
# Expected: ADMIN_SERVER=/home/<user>/Admin-Server

Copy cron expressions from status.sh output (step 0.6) — do not guess schedules.
Create or verify the six cron rows with API GET-before-POST when available. Match the absolute command exactly.
Terminal window
```
# Example row payload shape; repeat for each script from the table above.
# Do not include redirects, pipes, or $HOME in command.
command="bash /home/<user>/Admin-Server/scripts/snapshot-config.sh"
```
If the API is not available, add the same absolute commands in hPanel and verify five-field syntax (min hour dom mon dow). A UI preset is not enough; inspect the saved row.

Confirm log files update after the first interval with the freshness probe.

ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then
    echo "❌ STALE $label — missing $path"; exit 1
  fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE

Expected: every row prints ✅ fresh; any ❌ STALE row means the cron is not alive enough for app deploys.

External heartbeat wiring (MonSpark, Healthchecks, Better Stack, Cronitor, UptimeRobot)

External heartbeat monitors are layered on top of the local cron/log freshness gate. They are useful, but they are not a substitute for fresh Admin-Server logs. If the operator already pays for MonSpark, Better Stack, Cronitor, or UptimeRobot heartbeat monitors, use that tool here instead of signing up for a new Healthchecks.io account.

Script	Heartbeat slot	Provider examples
`snapshot-config.sh`	`HEARTBEAT_SNAPSHOT`	MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat
`integrity-check.sh`	`HEARTBEAT_INTEGRITY`	MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat
`resource-check.sh`	`HEARTBEAT_RESOURCE`	MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat
`error-log-check.sh`	`HEARTBEAT_ERRORLOG`	MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat
`domain-inventory.sh`	`HEARTBEAT_INVENTORY`	MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat

If a slot is blank, that script should still run locally but will not ping the external heartbeat provider. If you claim external heartbeat monitoring is configured, paste the heartbeat URLs into config/server.env, run the matching script once, and confirm the provider dashboard receives the ping. Leave blank slots explicitly documented as N/A — no external heartbeat configured.

For MonSpark specifically, create one Cron Job monitor per Admin-Server script and paste its URL into the matching HEARTBEAT_* slot. The MonSpark monitoring guide covers the full provider setup and optional Laravel MONSPARK_CRON_URL scheduler heartbeat.

0.9 · Discover server runtime paths

Record the server runtime paths the app deploys will consume.

ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
{
  echo "# Generated by setup-shared-hosting; update when hPanel PHP/Node changes."
  echo "PHP_LOGIN_SHELL=$(command -v php || true)"
  for phpbin in /opt/alt/php84/usr/bin/php /opt/alt/php83/usr/bin/php /opt/alt/php82/usr/bin/php /usr/local/bin/php /usr/bin/php; do
    [ -x "$phpbin" ] && printf 'PHP_CANDIDATE=%s # %s\n' "$phpbin" "$("$phpbin" -r 'echo PHP_VERSION;' 2>/dev/null || true)"
  done
  echo "COMPOSER_BIN=$(command -v composer || true)"
  echo "NODE_BIN=$(command -v node || true)"
  echo "NPM_BIN=$(command -v npm || true)"
} > config/server-environment.conf
cat config/server-environment.conf
git add config/server-environment.conf
git diff --cached --quiet || git commit -m "Record server environment paths"
REMOTE

Expected: config/server-environment.conf is committed and shows the login-shell PHP separately from versioned PHP candidates. Later deploy pages still confirm the domain’s selected web/CLI PHP before pinning Composer.

0.10 · First commit + push

Push the Admin-Server repo (baseline + monitored paths + committed config such as server-environment.conf).
Terminal window
```
ssh <SSH_ALIAS> '
  cd ~/Admin-Server
  git status
  git push
'
```

0.11 · Document the server (SHOULD)

Record in the project’s CLAUDE.local.md (or equivalent local-only notes): SSH alias, Admin-Hostinger-<account> repo name, last baseline date, last webhook rotation — not in git-tracked secrets.

Verify existing

When detect-and-skip found scripts already installed:

ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE

Fix only failed checks (missing baseline → 0.5; stale logs → 0.8; unset webhooks → 0.3 + 0.7). Then return to your app playbook.

If this verification is happening for a specific app domain, add that domain path to the integrity baseline before you return:

APP_DOMAIN="<domain.example.com>"
ssh <SSH_ALIAS> "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
APP_DOMAIN="${APP_DOMAIN:?set APP_DOMAIN before running}"
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the domain path; baseline regenerated

Idempotent re-run

Concern	On second run
Repo	`git fetch && git pull` — no re-clone
Cron	Detected before add — no duplicates
Baseline	Regeneration non-destructive
Health	`status.sh` + the log freshness probe

Secrets discipline

Webhook URLs are credentials — live only in 1Password and gitignored server.env; never in README files, examples, commits, screenshots, or chat.
A committed webhook URL is compromised. Delete/recreate the webhook, then update 1Password and server.env; editing nearby config is not recovery.
Before committing Admin-Server docs/config examples, run rg -n 'discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9._-]+' . and confirm there are no tracked Discord webhook URLs.
server.env: chmod 600, gitignored — interim SoT for ops / deploys / backups.
Prefer server-to-server copy or clipboard bridge at keyboard — never through agent chat.
P9C-1 (future): 1Password SA fetch replaces plaintext URLs — see Hardening.

Hardening `server.env`

Weakness	Interim	After P9C-1
Plaintext webhooks on disk	`chmod 600` + gitignore	SA fetch at runtime
No audit trail	Rotation log in monitoring state	1Password activity log
Per-server manual rotation	Operator checklist	Rotate vault once; servers pull fresh

Later hardening: move Discord/Slack webhook URLs out of plaintext server.env into a scoped read-only 1Password service-account fetch that fails closed. This is post-launch Admin-Server ops work, not a setup-new Phase 9 launch gate.

P9C-1 unblocks after the CodeCanyon payments setup proves op on Hostinger CloudLinux.

Checklist

Verification checklist:

What’s next

Machine setup Once per laptop — gh, MCP, op — pairs with this server gate.

CodeCanyon setup-new Per-app playbook — run after this account gate passes.

Three-tier admin model Admin-Local · Admin-Domain · Admin-Server + cascade resolver.

Deploy pipeline · step 1 Assumes Admin-Server paths resolve for deploys/backups webhooks.

Maintainer note

Source archives and intake ledgers stay out of reader-facing playbooks. The workflow above is the published server-readiness path.

When the gate passes, continue with CodeCanyon setup-new — Phase 1 workspace setup on your laptop.

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: Set up shared hosting
- url: https://library.zajapps.com/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: infrastructure
- subcategory: hosting
- topic: shared-hosting
- phase: shared-hosting
- part_number: 1 (legacy stepNumber frontmatter)
- legacy_step_number: 1
- est_time: ~2 min verify · ~15–25 min first install
- description: Once-per-account Admin-Server bootstrap — monitoring cron, ops/deploys/backups webhooks, MD5 baselines, and server.env before any Laravel deploy.
- tags: servers, shared-hosting, admin-server, hostinger, monitoring

## Execution rules (binding)
- This is Part 1 of phase shared-hosting (~2 min verify · ~15–25 min first install) — 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.
- 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.

---

# Set up shared hosting

## TL;DR

**Objective** — bootstrap the per-server **Admin-Server** toolkit on a fresh hosting account so config drift detection, MD5 integrity checks, disk/inode alerts, PHP error-log scanning, domain inventory, log rotation, and alert channels (`ops` · `deploys` · `backups`) are defined **once** for every app on that account.

:::note[For beginners and agents]
**Gate — done when** — `~/Admin-Server/scripts/status.sh` exits `0` and reports the expected identity, the log freshness probe reports no `STALE` rows, `monitored-paths.conf` includes `~/.ssh/authorized_keys` plus every app domain path being reused, and one synthetic alert arrives through an `ops` webhook with the correct env prefix: **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`**. Deploy, backup, and heartbeat slots are either configured or explicitly waived in `Zaj-PROJECT.md`; blank slots are no-ops, not proof that alerting works.

**Once per server, not per project.** Re-run only when you add a **new** hosting account. If scripts already exist, detect-and-skip — verify, do not reinstall.

**⏱ ~2 min** (verify) · **~15–25 min** (first install) · **🔀** all work over SSH on the server; **👤** Hostinger API/panel authorization + webhook paste in `nano` on the server.
:::

---

This is the **account-scoped server-readiness playbook** before [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) reaches deployment. Conceptual companion: [Three-tier admin (handbook)](/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/).

<StageFlow
  title="Once per account, then every app"
  stages={[
    { label: 'This account', sub: 'Admin-Server readiness', tone: 'core' },
    { label: 'App #1', sub: 'setup-new', tone: 'good' },
    { label: 'App #N', sub: 'reuse server tier', tone: 'muted' },
  ]}
/>

```mermaid
flowchart LR
  A["New hosting account"] --> B["Server readiness · this playbook"]
  B --> C["setup-new · app 1"]
  B --> D["setup-new · app N"]
```

## Operating rules

Every task in this phase follows four operating rules:

| Rule | Meaning |
| --- | --- |
| **Runs on the server** | SSH into `~/Admin-Server/` on the hosting account — zero toolkit binaries on your laptop |
| **Secrets stay server-side** | No webhook URL or SA token in laptop argv or agent chat — see [Secrets discipline](#secrets-discipline) |
| **Idempotent** | Re-run safe: `git pull`-friendly; baselines non-destructive; cron lines detected before duplicate add |
| **Secret source of truth** | Webhooks and heartbeat URLs are created/stored first in the shared infrastructure 1Password vault recorded in `Zaj-PROJECT.md` (default example: `General-Dev`); runtime copies live only in gitignored `server.env` at `chmod 600` |

:::danger[Presence is not liveness]
`~/Admin-Server/scripts/status.sh` can exist and still be stale if Hostinger cron jobs stopped weeks ago. A reusable Admin-Server must pass both checks: `status.sh` exits `0` **and** every expected log file is fresh within twice its cron interval. A `STALE` row blocks reuse until the cron is fixed and the script runs again.
:::

:::note[Pairing with laptop setup]
[Machine setup](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/) configures **your laptop** (`gh`, MCP, `op`). **This playbook configures each hosting account.** The two tracks are independent — run them in either order — but **both must complete before [Deploy pipeline](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/)** registers webhooks through Admin-Server's `deploys` channel. After this playbook, record the SSH alias and `Admin-Hostinger-<account>` repo name in the project's gitignored `CLAUDE.local.md`.
:::

### Tasks at a glance

| # | Task | Priority | Type |
| --- | --- | --- | --- |
| 0.1 | Clone Admin-Server toolkit + initial repo setup | MUST | CLI (SSH) |
| 0.2 | Download `op` 1Password CLI *(no root)* | MUST after P9C-1 | CLI |
| 0.3 | Bootstrap `config/server.env` from template | MUST | 👤 on server (`nano`) |
| 0.4 | Make scripts executable + `chmod 600` on `server.env` | MUST | CLI |
| 0.5 | Generate initial MD5 baseline | MUST | CLI |
| 0.6 | Run `status.sh` smoke test | MUST | CLI |
| 0.7 | Fire one synthetic alert through `ops` channel | MUST | CLI |
| 0.8 | Register Hostinger cron entries (6 lines, 5-field syntax) | MUST | API or 👤 hPanel UI |
| 0.9 | Discover server runtime paths | MUST | CLI |
| 0.10 | First commit + push to per-server private repo | MUST | CLI |
| 0.11 | Document server in `CLAUDE.local.md` | SHOULD | Manual |

:::caution[Agents — do not invent Admin-Server layout]
If task text references scripts that are missing on disk, follow the **Admin-Server cross-phase proposal** in `_Sources/laravel/codecanyon/server-setup/admin-server-cross-phase-integration-proposal.md` (§ "Initial server setup checklist") — do not flesh out paths from training-data guesses. Interim flow uses webhook URLs in `server.env`; P9C-1 replaces that with 1Password Service Account fetch.
:::

## Before you start

| Prerequisite | Verify |
| --- | --- |
| SSH public-key auth to the account | `ssh <SSH_ALIAS> 'echo ok'` — no password prompt |
| Private GitHub repo `Admin-Hostinger-<account>` | Empty repo OK for first push |
| Discord or Slack ops channel | Ops webhook ready for `#server-alerts` or the project's equivalent; configure only through the secret-safe flow below |
| Shared infrastructure 1Password vault | Record the actual vault name in `Zaj-PROJECT.md`; `General-Dev` is the default example, not a fixed requirement |
| Heartbeat provider decision | MonSpark, Healthchecks.io, Better Stack, Cronitor, UptimeRobot heartbeats, or `N/A` with reason |

## Detect and skip

Run before any install work:

```bash
   ssh <SSH_ALIAS> '
     if [ -x ~/Admin-Server/scripts/status.sh ]; then
       echo "Admin-Server present — run Verify existing next"
       ~/Admin-Server/scripts/status.sh
     else
       ls ~/Admin-Server/scripts/*.sh 2>/dev/null | head -10
     fi
   '
```

| Output | Action |
| --- | --- |
| `status.sh` or scripts listed | Jump to [Verify existing](#verify-existing) — skip setup steps 0.1–0.5 only after liveness passes |
| No such file | Continue with the [setup tasks](#tasks) |
| Scripts but no `lib/init.sh` or no `config/server.env` | Legacy layout — run [Migrate legacy installs to v2](#migrate-legacy-installs-to-v2) before cron or app reuse |

---

## Migrate legacy installs to v2

Run this branch when `~/Admin-Server/` exists but uses the older layout (`config/webhooks.conf`, missing `config/server.env`, missing `lib/init.sh`, or scripts that do not write the expected logs). Migration is not a pass by itself; after it, run [Verify existing](#verify-existing).

<Steps>

1. **Normalize the config layout without deleting legacy files.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   mkdir -p config logs baselines
   if [ ! -f config/server.env ]; then
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     echo "Created config/server.env from example; edit it before alerting checks."
   fi
   [ -f config/webhooks.conf ] && echo "Legacy config/webhooks.conf kept as read-only fallback."
   test -d lib || echo "Missing lib/ — pull the Admin-Server v2 repo before continuing."
   git status --short
   REMOTE
   ```

   Expected: `config/server.env` exists at `chmod 600`; legacy `webhooks.conf` is not deleted; missing `lib/` is treated as a blocker until the v2 repo is pulled.

2. **Complete the v2 gates.** Edit `server.env` with the slot matrix in step 0.3, register absolute-path cron rows in step 0.8, regenerate the baseline, then run [Verify existing](#verify-existing). A migrated server does not become deploy-ready until the freshness probe has no `STALE` rows.

</Steps>

## Tasks

Verification-first flow: **Clone → op CLI (P9C-1) → `server.env` → baseline → status + alert → cron liveness → runtime discovery → commit/push**.

### 0.1 · Clone Admin-Server toolkit

<Steps>

1. **Clone the per-server private repo** into `~/Admin-Server/`.

   ```bash
   ssh <SSH_ALIAS> '
     git clone git@github.com-<GITHUB_USER>:<GITHUB_USER>/Admin-Hostinger-<account>.git ~/Admin-Server
     cd ~/Admin-Server && git remote -v
   '
   # Expected: origin → your Admin-Hostinger-<account> repo
   ```

2. **If the directory already exists**, update instead of re-cloning.

   ```bash
   ssh <SSH_ALIAS> 'cd ~/Admin-Server && git fetch && git pull'
   ```

</Steps>

### 0.2 · `op` CLI *(deferred — P9C-1)*

Step **0.2** (download `op` 1Password CLI, no root) is **MUST after P9C-1**, not part of the interim bootstrap. For forward compatibility only, add an empty placeholder when editing `server.env` in step 0.3:

```bash
OP_SERVICE_ACCOUNT_TOKEN=""
```

Do not run `op signin` from an agent session.

### 0.3 · Bootstrap `config/server.env`

<Steps>

1. **Create `server.env` from the template** on the server only.

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

2. **Set identity and at least one ops webhook** from the shared infrastructure vault (paste URL in `nano` on server — never into chat).

   Minimum alerting-ready fields: `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` (`staging` \| `production`), plus `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS`. The source copy lives in 1Password, usually `op://General-Dev/...` unless `Zaj-PROJECT.md` names a different shared infrastructure vault.

</Steps>

:::danger[Installed ≠ alerting works]
`server.env` is the Admin-Server v2 runtime source of truth. A green `status.sh` proves scripts and cron freshness; it does **not** prove Slack, Discord, or external heartbeat destinations are wired. Empty alert or heartbeat values silently no-op. Do not mark the account alerting-ready until the synthetic `ops` alert reaches the expected channel and each adopted heartbeat monitor shows a fresh ping.
:::

| Slot | Variables | Required? | Behavior when blank |
| --- | --- | --- | --- |
| Server identity | `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` | Required | `status.sh` cannot prove the account identity |
| Ops alerts | `DISCORD_WEBHOOK_OPS`, `SLACK_WEBHOOK_OPS` | Required for alerting-ready | Monitoring alerts log locally only; this playbook's alert gate cannot pass |
| Deploy notifications | `DISCORD_WEBHOOK_DEPLOYS`, `SLACK_WEBHOOK_DEPLOYS` | Required when deploy notifications are enabled | Deployer Section J logs "notification skipped" and continues |
| Backup notifications | `DISCORD_WEBHOOK_BACKUPS`, `SLACK_WEBHOOK_BACKUPS` | Required when backup alerting is enabled | Backup alerts no-op or fall back to ops depending on the script |
| Legacy/default webhook | `WEBHOOK_URL` | Legacy fallback only | Current v2 scripts should prefer the channel-specific vars above |
| External heartbeat pings | `HEARTBEAT_SNAPSHOT`, `HEARTBEAT_INTEGRITY`, `HEARTBEAT_RESOURCE`, `HEARTBEAT_ERRORLOG`, `HEARTBEAT_INVENTORY` | Required when external heartbeat monitoring is claimed | Cron still runs locally, but MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot will not page on missed runs |
| Future 1Password fetch | `OP_SERVICE_ACCOUNT_TOKEN` | Empty until service-account hardening | `server.env` remains the runtime copy; source values stay in the shared infra vault |

### Wire alerting destinations

Alert channels are part of the server setup, not a later nice-to-have. Use the channel names below as the default map, then record the actual workspace/channel names in `Zaj-PROJECT.md`.

If an agent is driving Discord, Slack, or MonSpark through the operator's logged-in browser, use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/): click by accessibility-tree element refs, not screenshot coordinates; let the human own login and secret-copy moments; move copied URLs through clipboard → stdin so webhook and heartbeat URLs never print in chat, terminal output, or process lists.

| Route | Common destination | Variables |
| --- | --- | --- |
| Ops | `#server-alerts` | `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS` |
| Deploys | `#deployments` | `DISCORD_WEBHOOK_DEPLOYS` or `SLACK_WEBHOOK_DEPLOYS` |
| Backups | ops or backup channel | `DISCORD_WEBHOOK_BACKUPS` or `SLACK_WEBHOOK_BACKUPS` |
| App alerts | `#app-alerts` | App/Sentry/MonSpark routing, not Admin-Server deploy vars |

<Steps>

1. **Create or reuse provider webhooks** in the right workspace.

   - Discord: right-click channel → **Edit Channel** → **Integrations** → **Create Webhook** → rename → **Save** → **Copy URL**.
   - Slack: `api.slack.com/apps` → **Incoming Webhooks** → **Add to Workspace** → channel → **Copy**.
   - MonSpark heartbeats: **Cron Job** → **Create Monitor** → name/interval/grace → **Copy heartbeat URL**.
   - If the operator already has the right channel and webhook, reuse it; do not create duplicates.

2. **Store every URL in 1Password before it touches the server.**

   ```md
   Shared infra vault: <actual-vault-name>  # default example: General-Dev
   op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS
   op://<vault>/Admin-Server/SLACK_WEBHOOK_DEPLOYS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_DEPLOYS
   ```

3. **Smoke-test endpoints without printing secrets.**

   ```bash
   DISCORD_URL="$(op read 'op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS')"
   curl -fsS -o /dev/null -w '%{http_code}\n' "$DISCORD_URL"
   unset DISCORD_URL
   # Expected: 200 for Discord webhook GET metadata

   SLACK_URL="$(op read 'op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS')"
   printf '{"text":"Admin-Server webhook smoke test"}' \
     | curl -fsS -X POST -H 'Content-type: application/json' --data @- "$SLACK_URL"
   unset SLACK_URL
   # Expected: ok
   ```

   If a provider does not support a harmless preflight for that URL, skip the endpoint probe and rely on the real `send_alert`/`alert-helper` test after wiring.

4. **Paste into `config/server.env` through an interactive editor or secure clipboard bridge.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

   Never echo webhook URLs into terminal logs, agent chat, README files, screenshots, or commits.

5. **Verify with the shipped alert helper.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     if [ -x scripts/send_alert.sh ]; then
       bash scripts/send_alert.sh ops INFO "Admin-Server alerting smoke test for $(hostname)"
     else
       bash scripts/alert-helper.sh INFO "Admin-Server alerting smoke test for $(hostname)" ops
     fi
   '
   # Expected: exit 0 and the ops channel receives the message with the server env prefix.
   ```

</Steps>

### 0.4 · Executable scripts + `server.env` permissions

<Steps>

1. **chmod scripts and confirm `server.env` stays private.**

   ```bash
   ssh <SSH_ALIAS> '
     chmod +x ~/Admin-Server/scripts/*.sh
     chmod 600 ~/Admin-Server/config/server.env
     ls -l ~/Admin-Server/scripts/status.sh ~/Admin-Server/config/server.env
   '
   # Expected: scripts -rwx; server.env -rw------- 
   ```

</Steps>

### 0.5 · Generate initial MD5 baseline

<Steps>

1. **Generate and commit the integrity baseline.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     conf="config/monitored-paths.conf"
     touch "$conf"
     grep -Fxq "$HOME/.ssh/authorized_keys" "$conf" 2>/dev/null || printf "%s\n" "$HOME/.ssh/authorized_keys" >> "$conf"
     ~/Admin-Server/scripts/generate-baseline.sh
     git add "$conf" baselines/checksums.md5
     git diff --cached --quiet || git commit -m "Initial integrity baseline"
   '
   # Expected: checksums.md5 with server dotfiles and ~/.ssh/authorized_keys
   ```

</Steps>

### 0.6 · Run `status.sh` smoke test

<Steps>

1. **Run the health snapshot** — this is the **verify** step in the eight-step flow.

   ```bash
   ssh <SSH_ALIAS> '~/Admin-Server/scripts/status.sh'
   ```

	   Expected: clean `SERVER_LABEL` / `SERVER_ENV`; baseline ✅; webhook slots show ✅/❌ (at least one ✅ before you leave this playbook); **cron schedule printed** — use that output for the cron step.

</Steps>

### 0.7 · Fire one synthetic alert (`ops` channel)

<Steps>

1. **Send a test alert** through the ops channel.

   ```bash
   ssh <SSH_ALIAS> '
     ~/Admin-Server/scripts/alert-helper.sh INFO "Server-readiness smoke test" "Hello from $(hostname)" ops
   '
   ```

   **Expected:** Discord/Slack message with **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`** prefix.

</Steps>

### 0.8 · Register six Hostinger cron entries

Hostinger shared hosting often has **no** SSH `crontab` CLI. Use the Hostinger REST API when you have the account token; otherwise use hPanel → Advanced → Cron Jobs. Use SSH `crontab` only on hosts where `command -v crontab` succeeds.

:::caution[Hostinger cron commands are not shell scripts]
The Hostinger API/panel stores a command, but it does not safely expand `$HOME` or run shell operators for you. Use an absolute path such as `/home/<user>/Admin-Server/scripts/integrity-check.sh`, and keep redirects/pipes inside wrapper scripts if a command needs them.
:::

| Cron job | Typical script | Watches |
| --- | --- | --- |
| Config snapshot | `snapshot-config.sh` | Tracked config drift |
| MD5 integrity | `integrity-check.sh` | Baseline mutations |
| Disk / inode | `resource-check.sh` | Space and inode exhaustion |
| PHP error log | `error-log-check.sh` | New PHP errors across domains |
| Domain inventory | `domain-inventory.sh` | Apps/domains on account |
| Log rotation | `rotate-logs.sh` | Log volume |

<Steps>

1. **Resolve the absolute Admin-Server path** before creating any cron row.

   ```bash
   ssh <SSH_ALIAS> 'printf "ADMIN_SERVER=%s\n" "$HOME/Admin-Server"'
   # Expected: ADMIN_SERVER=/home/<user>/Admin-Server
   ```

2. **Copy cron expressions from `status.sh` output** (step 0.6) — do not guess schedules.

3. **Create or verify the six cron rows** with API GET-before-POST when available. Match the absolute command exactly.

   ```bash
   # Example row payload shape; repeat for each script from the table above.
   # Do not include redirects, pipes, or $HOME in command.
   command="bash /home/<user>/Admin-Server/scripts/snapshot-config.sh"
   ```

   If the API is not available, add the same absolute commands in hPanel and verify **five-field** syntax (`min hour dom mon dow`). A UI preset is not enough; inspect the saved row.

4. **Confirm log files update** after the first interval with the freshness probe.

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then
       echo "❌ STALE $label — missing $path"; exit 1
     fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   ```

   Expected: every row prints `✅ fresh`; any `❌ STALE` row means the cron is not alive enough for app deploys.

</Steps>

### External heartbeat wiring *(MonSpark, Healthchecks, Better Stack, Cronitor, UptimeRobot)*

External heartbeat monitors are layered on top of the local cron/log freshness gate. They are useful, but they are not a substitute for fresh Admin-Server logs. If the operator already pays for MonSpark, Better Stack, Cronitor, or UptimeRobot heartbeat monitors, use that tool here instead of signing up for a new Healthchecks.io account.

| Script | Heartbeat slot | Provider examples |
| --- | --- | --- |
| `snapshot-config.sh` | `HEARTBEAT_SNAPSHOT` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `integrity-check.sh` | `HEARTBEAT_INTEGRITY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `resource-check.sh` | `HEARTBEAT_RESOURCE` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `error-log-check.sh` | `HEARTBEAT_ERRORLOG` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `domain-inventory.sh` | `HEARTBEAT_INVENTORY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |

If a slot is blank, that script should still run locally but will not ping the external heartbeat provider. If you claim external heartbeat monitoring is configured, paste the heartbeat URLs into `config/server.env`, run the matching script once, and confirm the provider dashboard receives the ping. Leave blank slots explicitly documented as `N/A — no external heartbeat configured`.

For MonSpark specifically, create one **Cron Job** monitor per Admin-Server script and paste its URL into the matching `HEARTBEAT_*` slot. The [MonSpark monitoring guide](/tech-stack/laravel/codecanyon/learn/guides/monspark-monitoring/) covers the full provider setup and optional Laravel `MONSPARK_CRON_URL` scheduler heartbeat.

### 0.9 · Discover server runtime paths

<Steps>

1. **Record the server runtime paths the app deploys will consume.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   {
     echo "# Generated by setup-shared-hosting; update when hPanel PHP/Node changes."
     echo "PHP_LOGIN_SHELL=$(command -v php || true)"
     for phpbin in /opt/alt/php84/usr/bin/php /opt/alt/php83/usr/bin/php /opt/alt/php82/usr/bin/php /usr/local/bin/php /usr/bin/php; do
       [ -x "$phpbin" ] && printf 'PHP_CANDIDATE=%s # %s\n' "$phpbin" "$("$phpbin" -r 'echo PHP_VERSION;' 2>/dev/null || true)"
     done
     echo "COMPOSER_BIN=$(command -v composer || true)"
     echo "NODE_BIN=$(command -v node || true)"
     echo "NPM_BIN=$(command -v npm || true)"
   } > config/server-environment.conf
   cat config/server-environment.conf
   git add config/server-environment.conf
   git diff --cached --quiet || git commit -m "Record server environment paths"
   REMOTE
   ```

   Expected: `config/server-environment.conf` is committed and shows the login-shell PHP separately from versioned PHP candidates. Later deploy pages still confirm the domain's selected web/CLI PHP before pinning Composer.

</Steps>

### 0.10 · First commit + push

<Steps>

1. **Push the Admin-Server repo** (baseline + monitored paths + committed config such as `server-environment.conf`).

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     git status
     git push
   '
   ```

</Steps>

### 0.11 · Document the server *(SHOULD)*

Record in the project's **`CLAUDE.local.md`** (or equivalent local-only notes): SSH alias, `Admin-Hostinger-<account>` repo name, last baseline date, last webhook rotation — not in git-tracked secrets.

---

## Verify existing

When detect-and-skip found scripts already installed:

```bash
ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE
```

Fix only failed checks (missing baseline → 0.5; stale logs → 0.8; unset webhooks → 0.3 + 0.7). Then return to your app playbook.

If this verification is happening for a specific app domain, add that domain path to the integrity baseline before you return:

```bash
APP_DOMAIN="<domain.example.com>"
ssh <SSH_ALIAS> "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
APP_DOMAIN="${APP_DOMAIN:?set APP_DOMAIN before running}"
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the domain path; baseline regenerated
```

## Idempotent re-run

| Concern | On second run |
| --- | --- |
| Repo | `git fetch && git pull` — no re-clone |
| Cron | Detected before add — no duplicates |
| Baseline | Regeneration non-destructive |
| Health | `status.sh` + the log freshness probe |

## Secrets discipline

- Webhook URLs are **credentials** — live only in 1Password and gitignored `server.env`; never in README files, examples, commits, screenshots, or chat.
- A committed webhook URL is compromised. Delete/recreate the webhook, then update 1Password and `server.env`; editing nearby config is not recovery.
- Before committing Admin-Server docs/config examples, run `rg -n 'discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9._-]+' .` and confirm there are no tracked Discord webhook URLs.
- **`server.env`**: `chmod 600`, gitignored — interim SoT for `ops` / `deploys` / `backups`.  
- Prefer **server-to-server** copy or **clipboard bridge** at keyboard — never through agent chat.  
- **P9C-1 (future):** 1Password SA fetch replaces plaintext URLs — see [Hardening](#hardening-serverenv).

## Hardening `server.env`

| Weakness | Interim | After P9C-1 |
| --- | --- | --- |
| Plaintext webhooks on disk | `chmod 600` + gitignore | SA fetch at runtime |
| No audit trail | Rotation log in monitoring state | 1Password activity log |
| Per-server manual rotation | Operator checklist | Rotate vault once; servers pull fresh |

Later hardening: move Discord/Slack webhook URLs out of plaintext `server.env` into a scoped read-only 1Password service-account fetch that fails closed. This is post-launch Admin-Server ops work, not a setup-new Phase 9 launch gate.

P9C-1 unblocks after the CodeCanyon payments setup proves `op` on Hostinger CloudLinux.

---

## Checklist

Verification checklist:

- [ ] SSH alias works passwordlessly from laptop
- [ ] Server GitHub auth: `ssh -T git@github.com-<GITHUB_USER>` succeeds
- [ ] `~/Admin-Server/` present; `git remote -v` correct
- [ ] All monitoring scripts executable (`-rwx`)
- [ ] `config/server.env` exists at `chmod 600`, gitignored
- [ ] Six cron entries installed through Hostinger API/hPanel or SSH `crontab` when available; each row uses `bash /home/<user>/Admin-Server/scripts/<script>.sh` with no `$HOME`, pipes, or redirects
- [ ] Admin-Server logs are fresh within each cron interval ×2; no `STALE` rows
- [ ] `baselines/checksums.md5` exists with ≥4 entries
- [ ] Test alert received with `[STAGING] 🟡` or `[PRODUCTION] 🔴` prefix
- [ ] Adopted external heartbeat slots show fresh provider pings, or each blank slot is recorded as `N/A` with reason
- [ ] `config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's domain path before reuse
- [ ] `config/server-environment.conf` committed with PHP/Node/Composer path candidates
- [ ] Server documented in `CLAUDE.local.md` *(step 0.11)*

## What's next

<CardGrid>
  <LinkCard title="Machine setup" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/" description="Once per laptop — gh, MCP, op — pairs with this server gate." />
  <LinkCard title="CodeCanyon setup-new" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/" description="Per-app playbook — run after this account gate passes." />
  <LinkCard title="Three-tier admin model" href="/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/" description="Admin-Local · Admin-Domain · Admin-Server + cascade resolver." />
  <LinkCard title="Deploy pipeline · step 1" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/01-deployer/" description="Assumes Admin-Server paths resolve for deploys/backups webhooks." />
</CardGrid>

### Maintainer note

Source archives and intake ledgers stay out of reader-facing playbooks. The workflow above is the published server-readiness path.

:::next[Next: start a CodeCanyon project]
When the gate passes, continue with [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) — Phase 1 workspace setup on your laptop.
:::

# Set up shared hosting

> Source: https://library.zajapps.com/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/

## TL;DR

**Objective** — bootstrap the per-server **Admin-Server** toolkit on a fresh hosting account so config drift detection, MD5 integrity checks, disk/inode alerts, PHP error-log scanning, domain inventory, log rotation, and alert channels (`ops` · `deploys` · `backups`) are defined **once** for every app on that account.

:::note[For beginners and agents]
**Gate — done when** — `~/Admin-Server/scripts/status.sh` exits `0` and reports the expected identity, the log freshness probe reports no `STALE` rows, `monitored-paths.conf` includes `~/.ssh/authorized_keys` plus every app domain path being reused, and one synthetic alert arrives through an `ops` webhook with the correct env prefix: **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`**. Deploy, backup, and heartbeat slots are either configured or explicitly waived in `Zaj-PROJECT.md`; blank slots are no-ops, not proof that alerting works.

**Once per server, not per project.** Re-run only when you add a **new** hosting account. If scripts already exist, detect-and-skip — verify, do not reinstall.

**⏱ ~2 min** (verify) · **~15–25 min** (first install) · **🔀** all work over SSH on the server; **👤** Hostinger API/panel authorization + webhook paste in `nano` on the server.
:::

---

This is the **account-scoped server-readiness playbook** before [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) reaches deployment. Conceptual companion: [Three-tier admin (handbook)](/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/).

<StageFlow
  title="Once per account, then every app"
  stages={[
    { label: 'This account', sub: 'Admin-Server readiness', tone: 'core' },
    { label: 'App #1', sub: 'setup-new', tone: 'good' },
    { label: 'App #N', sub: 'reuse server tier', tone: 'muted' },
  ]}
/>

```mermaid
flowchart LR
  A["New hosting account"] --> B["Server readiness · this playbook"]
  B --> C["setup-new · app 1"]
  B --> D["setup-new · app N"]
```

## Operating rules

Every task in this phase follows four operating rules:

| Rule | Meaning |
| --- | --- |
| **Runs on the server** | SSH into `~/Admin-Server/` on the hosting account — zero toolkit binaries on your laptop |
| **Secrets stay server-side** | No webhook URL or SA token in laptop argv or agent chat — see [Secrets discipline](#secrets-discipline) |
| **Idempotent** | Re-run safe: `git pull`-friendly; baselines non-destructive; cron lines detected before duplicate add |
| **Secret source of truth** | Webhooks and heartbeat URLs are created/stored first in the shared infrastructure 1Password vault recorded in `Zaj-PROJECT.md` (default example: `General-Dev`); runtime copies live only in gitignored `server.env` at `chmod 600` |

:::danger[Presence is not liveness]
`~/Admin-Server/scripts/status.sh` can exist and still be stale if Hostinger cron jobs stopped weeks ago. A reusable Admin-Server must pass both checks: `status.sh` exits `0` **and** every expected log file is fresh within twice its cron interval. A `STALE` row blocks reuse until the cron is fixed and the script runs again.
:::

:::note[Pairing with laptop setup]
[Machine setup](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/) configures **your laptop** (`gh`, MCP, `op`). **This playbook configures each hosting account.** The two tracks are independent — run them in either order — but **both must complete before [Deploy pipeline](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/)** registers webhooks through Admin-Server's `deploys` channel. After this playbook, record the SSH alias and `Admin-Hostinger-<account>` repo name in the project's gitignored `CLAUDE.local.md`.
:::

### Tasks at a glance

| # | Task | Priority | Type |
| --- | --- | --- | --- |
| 0.1 | Clone Admin-Server toolkit + initial repo setup | MUST | CLI (SSH) |
| 0.2 | Download `op` 1Password CLI *(no root)* | MUST after P9C-1 | CLI |
| 0.3 | Bootstrap `config/server.env` from template | MUST | 👤 on server (`nano`) |
| 0.4 | Make scripts executable + `chmod 600` on `server.env` | MUST | CLI |
| 0.5 | Generate initial MD5 baseline | MUST | CLI |
| 0.6 | Run `status.sh` smoke test | MUST | CLI |
| 0.7 | Fire one synthetic alert through `ops` channel | MUST | CLI |
| 0.8 | Register Hostinger cron entries (6 lines, 5-field syntax) | MUST | API or 👤 hPanel UI |
| 0.9 | Discover server runtime paths | MUST | CLI |
| 0.10 | First commit + push to per-server private repo | MUST | CLI |
| 0.11 | Document server in `CLAUDE.local.md` | SHOULD | Manual |

:::caution[Agents — do not invent Admin-Server layout]
If task text references scripts that are missing on disk, follow the **Admin-Server cross-phase proposal** in `_Sources/laravel/codecanyon/server-setup/admin-server-cross-phase-integration-proposal.md` (§ "Initial server setup checklist") — do not flesh out paths from training-data guesses. Interim flow uses webhook URLs in `server.env`; P9C-1 replaces that with 1Password Service Account fetch.
:::

## Before you start

| Prerequisite | Verify |
| --- | --- |
| SSH public-key auth to the account | `ssh <SSH_ALIAS> 'echo ok'` — no password prompt |
| Private GitHub repo `Admin-Hostinger-<account>` | Empty repo OK for first push |
| Discord or Slack ops channel | Ops webhook ready for `#server-alerts` or the project's equivalent; configure only through the secret-safe flow below |
| Shared infrastructure 1Password vault | Record the actual vault name in `Zaj-PROJECT.md`; `General-Dev` is the default example, not a fixed requirement |
| Heartbeat provider decision | MonSpark, Healthchecks.io, Better Stack, Cronitor, UptimeRobot heartbeats, or `N/A` with reason |

## Detect and skip

Run before any install work:

```bash
   ssh <SSH_ALIAS> '
     if [ -x ~/Admin-Server/scripts/status.sh ]; then
       echo "Admin-Server present — run Verify existing next"
       ~/Admin-Server/scripts/status.sh
     else
       ls ~/Admin-Server/scripts/*.sh 2>/dev/null | head -10
     fi
   '
```

| Output | Action |
| --- | --- |
| `status.sh` or scripts listed | Jump to [Verify existing](#verify-existing) — skip setup steps 0.1–0.5 only after liveness passes |
| No such file | Continue with the [setup tasks](#tasks) |
| Scripts but no `lib/init.sh` or no `config/server.env` | Legacy layout — run [Migrate legacy installs to v2](#migrate-legacy-installs-to-v2) before cron or app reuse |

---

## Migrate legacy installs to v2

Run this branch when `~/Admin-Server/` exists but uses the older layout (`config/webhooks.conf`, missing `config/server.env`, missing `lib/init.sh`, or scripts that do not write the expected logs). Migration is not a pass by itself; after it, run [Verify existing](#verify-existing).

<Steps>

1. **Normalize the config layout without deleting legacy files.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   mkdir -p config logs baselines
   if [ ! -f config/server.env ]; then
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     echo "Created config/server.env from example; edit it before alerting checks."
   fi
   [ -f config/webhooks.conf ] && echo "Legacy config/webhooks.conf kept as read-only fallback."
   test -d lib || echo "Missing lib/ — pull the Admin-Server v2 repo before continuing."
   git status --short
   REMOTE
   ```

   Expected: `config/server.env` exists at `chmod 600`; legacy `webhooks.conf` is not deleted; missing `lib/` is treated as a blocker until the v2 repo is pulled.

2. **Complete the v2 gates.** Edit `server.env` with the slot matrix in step 0.3, register absolute-path cron rows in step 0.8, regenerate the baseline, then run [Verify existing](#verify-existing). A migrated server does not become deploy-ready until the freshness probe has no `STALE` rows.

</Steps>

## Tasks

Verification-first flow: **Clone → op CLI (P9C-1) → `server.env` → baseline → status + alert → cron liveness → runtime discovery → commit/push**.

### 0.1 · Clone Admin-Server toolkit

<Steps>

1. **Clone the per-server private repo** into `~/Admin-Server/`.

   ```bash
   ssh <SSH_ALIAS> '
     git clone git@github.com-<GITHUB_USER>:<GITHUB_USER>/Admin-Hostinger-<account>.git ~/Admin-Server
     cd ~/Admin-Server && git remote -v
   '
   # Expected: origin → your Admin-Hostinger-<account> repo
   ```

2. **If the directory already exists**, update instead of re-cloning.

   ```bash
   ssh <SSH_ALIAS> 'cd ~/Admin-Server && git fetch && git pull'
   ```

</Steps>

### 0.2 · `op` CLI *(deferred — P9C-1)*

Step **0.2** (download `op` 1Password CLI, no root) is **MUST after P9C-1**, not part of the interim bootstrap. For forward compatibility only, add an empty placeholder when editing `server.env` in step 0.3:

```bash
OP_SERVICE_ACCOUNT_TOKEN=""
```

Do not run `op signin` from an agent session.

### 0.3 · Bootstrap `config/server.env`

<Steps>

1. **Create `server.env` from the template** on the server only.

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     cp config/server.env.example config/server.env
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

2. **Set identity and at least one ops webhook** from the shared infrastructure vault (paste URL in `nano` on server — never into chat).

   Minimum alerting-ready fields: `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` (`staging` \| `production`), plus `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS`. The source copy lives in 1Password, usually `op://General-Dev/...` unless `Zaj-PROJECT.md` names a different shared infrastructure vault.

</Steps>

:::danger[Installed ≠ alerting works]
`server.env` is the Admin-Server v2 runtime source of truth. A green `status.sh` proves scripts and cron freshness; it does **not** prove Slack, Discord, or external heartbeat destinations are wired. Empty alert or heartbeat values silently no-op. Do not mark the account alerting-ready until the synthetic `ops` alert reaches the expected channel and each adopted heartbeat monitor shows a fresh ping.
:::

| Slot | Variables | Required? | Behavior when blank |
| --- | --- | --- | --- |
| Server identity | `SERVER_NAME`, `SERVER_LABEL`, `SERVER_ENV` | Required | `status.sh` cannot prove the account identity |
| Ops alerts | `DISCORD_WEBHOOK_OPS`, `SLACK_WEBHOOK_OPS` | Required for alerting-ready | Monitoring alerts log locally only; this playbook's alert gate cannot pass |
| Deploy notifications | `DISCORD_WEBHOOK_DEPLOYS`, `SLACK_WEBHOOK_DEPLOYS` | Required when deploy notifications are enabled | Deployer Section J logs "notification skipped" and continues |
| Backup notifications | `DISCORD_WEBHOOK_BACKUPS`, `SLACK_WEBHOOK_BACKUPS` | Required when backup alerting is enabled | Backup alerts no-op or fall back to ops depending on the script |
| Legacy/default webhook | `WEBHOOK_URL` | Legacy fallback only | Current v2 scripts should prefer the channel-specific vars above |
| External heartbeat pings | `HEARTBEAT_SNAPSHOT`, `HEARTBEAT_INTEGRITY`, `HEARTBEAT_RESOURCE`, `HEARTBEAT_ERRORLOG`, `HEARTBEAT_INVENTORY` | Required when external heartbeat monitoring is claimed | Cron still runs locally, but MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot will not page on missed runs |
| Future 1Password fetch | `OP_SERVICE_ACCOUNT_TOKEN` | Empty until service-account hardening | `server.env` remains the runtime copy; source values stay in the shared infra vault |

### Wire alerting destinations

Alert channels are part of the server setup, not a later nice-to-have. Use the channel names below as the default map, then record the actual workspace/channel names in `Zaj-PROJECT.md`.

If an agent is driving Discord, Slack, or MonSpark through the operator's logged-in browser, use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/): click by accessibility-tree element refs, not screenshot coordinates; let the human own login and secret-copy moments; move copied URLs through clipboard → stdin so webhook and heartbeat URLs never print in chat, terminal output, or process lists.

| Route | Common destination | Variables |
| --- | --- | --- |
| Ops | `#server-alerts` | `DISCORD_WEBHOOK_OPS` or `SLACK_WEBHOOK_OPS` |
| Deploys | `#deployments` | `DISCORD_WEBHOOK_DEPLOYS` or `SLACK_WEBHOOK_DEPLOYS` |
| Backups | ops or backup channel | `DISCORD_WEBHOOK_BACKUPS` or `SLACK_WEBHOOK_BACKUPS` |
| App alerts | `#app-alerts` | App/Sentry/MonSpark routing, not Admin-Server deploy vars |

<Steps>

1. **Create or reuse provider webhooks** in the right workspace.

   - Discord: right-click channel → **Edit Channel** → **Integrations** → **Create Webhook** → rename → **Save** → **Copy URL**.
   - Slack: `api.slack.com/apps` → **Incoming Webhooks** → **Add to Workspace** → channel → **Copy**.
   - MonSpark heartbeats: **Cron Job** → **Create Monitor** → name/interval/grace → **Copy heartbeat URL**.
   - If the operator already has the right channel and webhook, reuse it; do not create duplicates.

2. **Store every URL in 1Password before it touches the server.**

   ```md
   Shared infra vault: <actual-vault-name>  # default example: General-Dev
   op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS
   op://<vault>/Admin-Server/SLACK_WEBHOOK_DEPLOYS
   op://<vault>/Admin-Server/DISCORD_WEBHOOK_DEPLOYS
   ```

3. **Smoke-test endpoints without printing secrets.**

   ```bash
   DISCORD_URL="$(op read 'op://<vault>/Admin-Server/DISCORD_WEBHOOK_OPS')"
   curl -fsS -o /dev/null -w '%{http_code}\n' "$DISCORD_URL"
   unset DISCORD_URL
   # Expected: 200 for Discord webhook GET metadata

   SLACK_URL="$(op read 'op://<vault>/Admin-Server/SLACK_WEBHOOK_OPS')"
   printf '{"text":"Admin-Server webhook smoke test"}' \
     | curl -fsS -X POST -H 'Content-type: application/json' --data @- "$SLACK_URL"
   unset SLACK_URL
   # Expected: ok
   ```

   If a provider does not support a harmless preflight for that URL, skip the endpoint probe and rely on the real `send_alert`/`alert-helper` test after wiring.

4. **Paste into `config/server.env` through an interactive editor or secure clipboard bridge.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     chmod 600 config/server.env
     nano config/server.env
   '
   ```

   Never echo webhook URLs into terminal logs, agent chat, README files, screenshots, or commits.

5. **Verify with the shipped alert helper.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     if [ -x scripts/send_alert.sh ]; then
       bash scripts/send_alert.sh ops INFO "Admin-Server alerting smoke test for $(hostname)"
     else
       bash scripts/alert-helper.sh INFO "Admin-Server alerting smoke test for $(hostname)" ops
     fi
   '
   # Expected: exit 0 and the ops channel receives the message with the server env prefix.
   ```

</Steps>

### 0.4 · Executable scripts + `server.env` permissions

<Steps>

1. **chmod scripts and confirm `server.env` stays private.**

   ```bash
   ssh <SSH_ALIAS> '
     chmod +x ~/Admin-Server/scripts/*.sh
     chmod 600 ~/Admin-Server/config/server.env
     ls -l ~/Admin-Server/scripts/status.sh ~/Admin-Server/config/server.env
   '
   # Expected: scripts -rwx; server.env -rw------- 
   ```

</Steps>

### 0.5 · Generate initial MD5 baseline

<Steps>

1. **Generate and commit the integrity baseline.**

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     conf="config/monitored-paths.conf"
     touch "$conf"
     grep -Fxq "$HOME/.ssh/authorized_keys" "$conf" 2>/dev/null || printf "%s\n" "$HOME/.ssh/authorized_keys" >> "$conf"
     ~/Admin-Server/scripts/generate-baseline.sh
     git add "$conf" baselines/checksums.md5
     git diff --cached --quiet || git commit -m "Initial integrity baseline"
   '
   # Expected: checksums.md5 with server dotfiles and ~/.ssh/authorized_keys
   ```

</Steps>

### 0.6 · Run `status.sh` smoke test

<Steps>

1. **Run the health snapshot** — this is the **verify** step in the eight-step flow.

   ```bash
   ssh <SSH_ALIAS> '~/Admin-Server/scripts/status.sh'
   ```

	   Expected: clean `SERVER_LABEL` / `SERVER_ENV`; baseline ✅; webhook slots show ✅/❌ (at least one ✅ before you leave this playbook); **cron schedule printed** — use that output for the cron step.

</Steps>

### 0.7 · Fire one synthetic alert (`ops` channel)

<Steps>

1. **Send a test alert** through the ops channel.

   ```bash
   ssh <SSH_ALIAS> '
     ~/Admin-Server/scripts/alert-helper.sh INFO "Server-readiness smoke test" "Hello from $(hostname)" ops
   '
   ```

   **Expected:** Discord/Slack message with **`[STAGING] 🟡`** or **`[PRODUCTION] 🔴`** prefix.

</Steps>

### 0.8 · Register six Hostinger cron entries

Hostinger shared hosting often has **no** SSH `crontab` CLI. Use the Hostinger REST API when you have the account token; otherwise use hPanel → Advanced → Cron Jobs. Use SSH `crontab` only on hosts where `command -v crontab` succeeds.

:::caution[Hostinger cron commands are not shell scripts]
The Hostinger API/panel stores a command, but it does not safely expand `$HOME` or run shell operators for you. Use an absolute path such as `/home/<user>/Admin-Server/scripts/integrity-check.sh`, and keep redirects/pipes inside wrapper scripts if a command needs them.
:::

| Cron job | Typical script | Watches |
| --- | --- | --- |
| Config snapshot | `snapshot-config.sh` | Tracked config drift |
| MD5 integrity | `integrity-check.sh` | Baseline mutations |
| Disk / inode | `resource-check.sh` | Space and inode exhaustion |
| PHP error log | `error-log-check.sh` | New PHP errors across domains |
| Domain inventory | `domain-inventory.sh` | Apps/domains on account |
| Log rotation | `rotate-logs.sh` | Log volume |

<Steps>

1. **Resolve the absolute Admin-Server path** before creating any cron row.

   ```bash
   ssh <SSH_ALIAS> 'printf "ADMIN_SERVER=%s\n" "$HOME/Admin-Server"'
   # Expected: ADMIN_SERVER=/home/<user>/Admin-Server
   ```

2. **Copy cron expressions from `status.sh` output** (step 0.6) — do not guess schedules.

3. **Create or verify the six cron rows** with API GET-before-POST when available. Match the absolute command exactly.

   ```bash
   # Example row payload shape; repeat for each script from the table above.
   # Do not include redirects, pipes, or $HOME in command.
   command="bash /home/<user>/Admin-Server/scripts/snapshot-config.sh"
   ```

   If the API is not available, add the same absolute commands in hPanel and verify **five-field** syntax (`min hour dom mon dow`). A UI preset is not enough; inspect the saved row.

4. **Confirm log files update** after the first interval with the freshness probe.

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then
       echo "❌ STALE $label — missing $path"; exit 1
     fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   ```

   Expected: every row prints `✅ fresh`; any `❌ STALE` row means the cron is not alive enough for app deploys.

</Steps>

### External heartbeat wiring *(MonSpark, Healthchecks, Better Stack, Cronitor, UptimeRobot)*

External heartbeat monitors are layered on top of the local cron/log freshness gate. They are useful, but they are not a substitute for fresh Admin-Server logs. If the operator already pays for MonSpark, Better Stack, Cronitor, or UptimeRobot heartbeat monitors, use that tool here instead of signing up for a new Healthchecks.io account.

| Script | Heartbeat slot | Provider examples |
| --- | --- | --- |
| `snapshot-config.sh` | `HEARTBEAT_SNAPSHOT` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `integrity-check.sh` | `HEARTBEAT_INTEGRITY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `resource-check.sh` | `HEARTBEAT_RESOURCE` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `error-log-check.sh` | `HEARTBEAT_ERRORLOG` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |
| `domain-inventory.sh` | `HEARTBEAT_INVENTORY` | MonSpark Cron Job · Healthchecks ping · Better Stack/Cronitor/UptimeRobot heartbeat |

If a slot is blank, that script should still run locally but will not ping the external heartbeat provider. If you claim external heartbeat monitoring is configured, paste the heartbeat URLs into `config/server.env`, run the matching script once, and confirm the provider dashboard receives the ping. Leave blank slots explicitly documented as `N/A — no external heartbeat configured`.

For MonSpark specifically, create one **Cron Job** monitor per Admin-Server script and paste its URL into the matching `HEARTBEAT_*` slot. The [MonSpark monitoring guide](/tech-stack/laravel/codecanyon/learn/guides/monspark-monitoring/) covers the full provider setup and optional Laravel `MONSPARK_CRON_URL` scheduler heartbeat.

### 0.9 · Discover server runtime paths

<Steps>

1. **Record the server runtime paths the app deploys will consume.**

   ```bash
   ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   {
     echo "# Generated by setup-shared-hosting; update when hPanel PHP/Node changes."
     echo "PHP_LOGIN_SHELL=$(command -v php || true)"
     for phpbin in /opt/alt/php84/usr/bin/php /opt/alt/php83/usr/bin/php /opt/alt/php82/usr/bin/php /usr/local/bin/php /usr/bin/php; do
       [ -x "$phpbin" ] && printf 'PHP_CANDIDATE=%s # %s\n' "$phpbin" "$("$phpbin" -r 'echo PHP_VERSION;' 2>/dev/null || true)"
     done
     echo "COMPOSER_BIN=$(command -v composer || true)"
     echo "NODE_BIN=$(command -v node || true)"
     echo "NPM_BIN=$(command -v npm || true)"
   } > config/server-environment.conf
   cat config/server-environment.conf
   git add config/server-environment.conf
   git diff --cached --quiet || git commit -m "Record server environment paths"
   REMOTE
   ```

   Expected: `config/server-environment.conf` is committed and shows the login-shell PHP separately from versioned PHP candidates. Later deploy pages still confirm the domain's selected web/CLI PHP before pinning Composer.

</Steps>

### 0.10 · First commit + push

<Steps>

1. **Push the Admin-Server repo** (baseline + monitored paths + committed config such as `server-environment.conf`).

   ```bash
   ssh <SSH_ALIAS> '
     cd ~/Admin-Server
     git status
     git push
   '
   ```

</Steps>

### 0.11 · Document the server *(SHOULD)*

Record in the project's **`CLAUDE.local.md`** (or equivalent local-only notes): SSH alias, `Admin-Hostinger-<account>` repo name, last baseline date, last webhook rotation — not in git-tracked secrets.

---

## Verify existing

When detect-and-skip found scripts already installed:

```bash
ssh <SSH_ALIAS> 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE
```

Fix only failed checks (missing baseline → 0.5; stale logs → 0.8; unset webhooks → 0.3 + 0.7). Then return to your app playbook.

If this verification is happening for a specific app domain, add that domain path to the integrity baseline before you return:

```bash
APP_DOMAIN="<domain.example.com>"
ssh <SSH_ALIAS> "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
APP_DOMAIN="${APP_DOMAIN:?set APP_DOMAIN before running}"
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the domain path; baseline regenerated
```

## Idempotent re-run

| Concern | On second run |
| --- | --- |
| Repo | `git fetch && git pull` — no re-clone |
| Cron | Detected before add — no duplicates |
| Baseline | Regeneration non-destructive |
| Health | `status.sh` + the log freshness probe |

## Secrets discipline

- Webhook URLs are **credentials** — live only in 1Password and gitignored `server.env`; never in README files, examples, commits, screenshots, or chat.
- A committed webhook URL is compromised. Delete/recreate the webhook, then update 1Password and `server.env`; editing nearby config is not recovery.
- Before committing Admin-Server docs/config examples, run `rg -n 'discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9._-]+' .` and confirm there are no tracked Discord webhook URLs.
- **`server.env`**: `chmod 600`, gitignored — interim SoT for `ops` / `deploys` / `backups`.  
- Prefer **server-to-server** copy or **clipboard bridge** at keyboard — never through agent chat.  
- **P9C-1 (future):** 1Password SA fetch replaces plaintext URLs — see [Hardening](#hardening-serverenv).

## Hardening `server.env`

| Weakness | Interim | After P9C-1 |
| --- | --- | --- |
| Plaintext webhooks on disk | `chmod 600` + gitignore | SA fetch at runtime |
| No audit trail | Rotation log in monitoring state | 1Password activity log |
| Per-server manual rotation | Operator checklist | Rotate vault once; servers pull fresh |

Later hardening: move Discord/Slack webhook URLs out of plaintext `server.env` into a scoped read-only 1Password service-account fetch that fails closed. This is post-launch Admin-Server ops work, not a setup-new Phase 9 launch gate.

P9C-1 unblocks after the CodeCanyon payments setup proves `op` on Hostinger CloudLinux.

---

## Checklist

Verification checklist:

- [ ] SSH alias works passwordlessly from laptop
- [ ] Server GitHub auth: `ssh -T git@github.com-<GITHUB_USER>` succeeds
- [ ] `~/Admin-Server/` present; `git remote -v` correct
- [ ] All monitoring scripts executable (`-rwx`)
- [ ] `config/server.env` exists at `chmod 600`, gitignored
- [ ] Six cron entries installed through Hostinger API/hPanel or SSH `crontab` when available; each row uses `bash /home/<user>/Admin-Server/scripts/<script>.sh` with no `$HOME`, pipes, or redirects
- [ ] Admin-Server logs are fresh within each cron interval ×2; no `STALE` rows
- [ ] `baselines/checksums.md5` exists with ≥4 entries
- [ ] Test alert received with `[STAGING] 🟡` or `[PRODUCTION] 🔴` prefix
- [ ] Adopted external heartbeat slots show fresh provider pings, or each blank slot is recorded as `N/A` with reason
- [ ] `config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's domain path before reuse
- [ ] `config/server-environment.conf` committed with PHP/Node/Composer path candidates
- [ ] Server documented in `CLAUDE.local.md` *(step 0.11)*

## What's next

<CardGrid>
  <LinkCard title="Machine setup" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/" description="Once per laptop — gh, MCP, op — pairs with this server gate." />
  <LinkCard title="CodeCanyon setup-new" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/" description="Per-app playbook — run after this account gate passes." />
  <LinkCard title="Three-tier admin model" href="/tech-stack/laravel/codecanyon/learn/handbooks/02-three-tier-admin/" description="Admin-Local · Admin-Domain · Admin-Server + cascade resolver." />
  <LinkCard title="Deploy pipeline · step 1" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/04-deploy-pipeline/01-deployer/" description="Assumes Admin-Server paths resolve for deploys/backups webhooks." />
</CardGrid>

### Maintainer note

Source archives and intake ledgers stay out of reader-facing playbooks. The workflow above is the published server-readiness path.

:::next[Next: start a CodeCanyon project]
When the gate passes, continue with [CodeCanyon setup-new](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) — Phase 1 workspace setup on your laptop.
:::