7 · Optional tooling

TL;DR

Objective — add optional power-ups only where they fill a real gap: Atlas schema management, a database GUI (Bytebase), Redis caching via Herd Pro, and a right-sized debug-tools stack. None block launch; each has a free fallback.

User part + done-when

👤 User part — only for the tools you actually adopt: log in to Atlas Cloud, create a Bytebase workspace and whitelist its egress IP, or start the Herd Redis service in the GUI. Everything else is terminal-runnable, and you can skip the whole page.

Done when each tool is either installed where it adds value or skipped with the free fallback noted; if Redis is added, redis-cli ping returns PONG and tinker returns "Redis works!"; debug tools have no duplicate request inspectors; and Phase 3 is complete.  ·  ⏱ ~varies  ·  🔀 mixed (mostly 🤖; 👤 for cloud sign-ins / GUI service start).

Background

Everything here is optional — the phase is complete without it. Add a tool only when it fills a real gap for your project, and prefer the free fallback if you don’t already own the paid service.

Steps

1. Atlas — schema management

Atlas gives clean schema exports and cross-environment diffs (it’s the preferred exporter on page 5). The CLI is free; Atlas Cloud’s visual diffs and CI checks need a license.

1. Install the CLI and sign in. The CLI install is terminal-runnable; the atlas login browser sign-in is a 👤 step if you want Cloud features.

   atlas version 2>/dev/null || brew install ariga/tap/atlas
   atlas login && atlas whoami
   # Expected: a version, then your Atlas identity after the browser login

   • ✅ The Atlas CLI is installed (and signed in if you use Cloud).

2. Point it at the local DB via an env var — keep secrets out of atlas.hcl — and gitignore the env files.

   echo 'ATLAS_LOCAL_URL="mysql://root:@127.0.0.1:3306/[PROJECT_NAME]_local"' > .env.atlas
   grep -q '^\.env\.atlas$' .gitignore || printf '.env.atlas\n' >> .gitignore
   grep -q '^\.envrc$' .gitignore || printf '.envrc\n' >> .gitignore
   # Expected: .env.atlas written and both env files added to .gitignore

   • ✅ Atlas reads the DB URL from a gitignored env file.

Free fallback

You don’t need Atlas at all: mysqldump --no-data for snapshots (page 5), diff for comparison, and TablePlus (free tier) or DBeaver (open source) for visual inspection. Skip the Cloud push entirely if your plan is expired.

2. Bytebase — database GUI & review workflow

Bytebase adds a web UI for schema management, SQL review, and approval workflows across staging/production. It’s a heavier setup (~60–90 min) and only worth it for teams running frequent reviewed schema changes.

Who does this

👤 User creates the Bytebase workspace and connects the database instances — a web-account flow (sign-up, instance whitelisting, project setup) that an agent can’t drive.

1. Stand up the workspace and connect your instances.

   • Create a free workspace at hub.bytebase.com.

   • Add your staging and production instances (whitelist Bytebase’s egress IP in Remote MySQL first).

   • Create a project, transfer the databases in, sync schemas, and attach an SQL-review policy.

   • ✅ Bytebase is connected to your instances with a review policy attached.

Free fallback

TablePlus, DBeaver, panel phpMyAdmin, plus php artisan migrate:status and mysqldump --no-data cover the same ground for a solo developer.

3. Redis cache via Herd Pro

Redis replaces file-based cache/sessions/queues — 2–3× faster page loads, instant sessions. Not required for launch, and easy to add post-deploy. Local dev uses Herd Pro’s built-in Redis; staging/production use Upstash (configured in Phase 4/5).

Who does this

👤 User starts (or adds) the Local_Redis service in Herd → Services → Cache & Queue — a GUI toggle an agent can’t click. The Predis install, .env wiring, and verification below are terminal-runnable.

1. Start the Herd Redis service, then confirm it answers.

   redis-cli ping   # expect PONG
   # Expected: PONG

   • ✅ redis-cli ping returns PONG.

2. Require Predis — pin the platform PHP first if the server runs older PHP.

   SERVER_PHP_VERSION="<php-version-from-host>"
   composer config platform.php "$SERVER_PHP_VERSION"   # writes a permanent committed pin into composer.json; log it in _CUSTOMIZATIONS.md
   composer require predis/predis
   # Expected: Predis resolves to a server-compatible version and installs

   • ✅ Predis is installed against the server’s PHP version.

3. Wire local .env to the Herd Redis (no password, localhost).

   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis
   REDIS_CLIENT=predis
   REDIS_HOST=127.0.0.1
   REDIS_PASSWORD=null   # leave unquoted — null is a literal token; "null" breaks auth (exception to the double-quote-secrets rule)
   REDIS_PORT=6379
   REDIS_PREFIX=[PROJECT_NAME]_local_

   • ✅ .env points cache/session/queue at the local Redis.

4. Verify through tinker, then commit the lock-file change.

   php artisan config:clear && php artisan cache:clear
   php artisan tinker --execute="Cache::put('t','Redis works!',60); echo Cache::get('t');"
   git add composer.json composer.lock && git commit -m "Add Redis cache support via Predis"
   # Expected: "Redis works!" prints, then the lock-file commit is created

   • ✅ Tinker returns Redis works! and the lock change is committed.

Prepare (don’t populate) the Upstash placeholders in your .env.staging / .env.production templates for the deploy phase.

Match the server PHP before installing Predis

If the server runs an older PHP than your local machine, pin the platform first (composer config platform.php "$SERVER_PHP_VERSION") so Composer resolves a server-compatible Predis.

If you’re not on Herd Pro, any of these gives you the same local Redis:

No Herd Pro?

brew install redis && brew services start redis, docker run -d -p 6379:6379 redis:alpine, or DBngin — or simply keep CACHE_DRIVER=file locally and only use Redis (Upstash) on the server.

4. Debug tools — install only what fills a gap

Shipping without a request/query inspector is guesswork — but many CodeCanyon apps already ship barryvdh/laravel-debugbar. Installing Telescope on top creates competing toolbars and double-captures queries. Check first.

1. Check what’s already present.

   grep -c '"name": "barryvdh/laravel-debugbar"' composer.lock
   grep -c '"name": "laravel/telescope"' composer.lock
   # Expected: a 0/1 count for each — tells you what's already installed

   • ✅ The inspectors already in composer.lock are known.

2. Add at most one, based on what’s present.

   Already present	Action
   debugbar only	Keep it — you have request/query visibility. Don’t add Telescope.
   Telescope only	Keep it.
   Neither	Add one — debugbar for a quick bottom-bar, Telescope for a richer dashboard.

   • ✅ Exactly one request/query inspector is active — no duplicates.

Sentry and Ray are conditional

A Sentry SDK without a real DSN is dead code locally — install the SDK + publish config here only if you’ll wire it up, and do the actual DSN + test event in Phase 4 (don’t create a Sentry project now). Match the server PHP with composer config platform.php before requiring the Sentry SDK. Spatie Ray only helps if you own the paid Ray desktop app — skip otherwise.

Checklist

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

• 🔀 Per-tool decision made — installed where it adds value, or skipped with the free fallback noted.
• 🔀 Redis (if added) — redis-cli ping → PONG and tinker returns "Redis works!".
• 🤖 No duplicate inspectors — not both debugbar and Telescope.
• 🤖 Phase 3 complete — local environment installed, verified, committed, and secured.

→Next step

Phase 4 · Deploy pipeline