Operations

Use this page during deploys, upgrades, incidents, and production checks.

First Checks

Symptom	Check
Public pages are stale	Cache state, queue worker, optional HTML Cache package, CDN purge.
Admin is missing pages/settings	`php artisan optimize:clear`, permissions, package install state.
Install fails in CI	Missing non-interactive flags or private Composer credentials.
Marketplace cannot install	Account connection, Marketplace URL, webhook URL, package compatibility.
Public output looks unsafe	Search response HTML for authoring markers, model IDs, signed admin URLs, selectors, package names.

Site Health

Site Health is the operator-facing read-only page for launch and post-deploy checks. It should show whether public traffic can be served safely before anyone edits content.

Use it to check:

cache and static-output state
public HTML safety
server/runtime readiness
optimizer/static generation readiness when optional packages are installed
package and extension health signals

If Site Health reports a missing optional package table, check whether the package is installed and whether its migrations have run before treating it as a host bug.

Use the Site Health runbook for the full check list.

Lockdown

Lockdown blocks public frontend traffic and most admin access during a suspected compromise or high-risk maintenance window. Break-glass admins can still access the admin surface.

Use Lockdown when:

public content may be unsafe
package state is inconsistent after a failed deploy
you need to stop cached public pages while investigating

After enabling or disabling Lockdown, clear runtime caches and verify public routes from a signed-out browser.

Upgrades

Standard host upgrade flow:

composer update capell-app/capell -W
php artisan capell:upgrade
php artisan optimize:clear
php artisan queue:restart

Before upgrading production, check:

database backup exists
queue workers can run
optional package migrations are included
php artisan list capell shows expected package commands
Site Health is clean or known issues are documented

Rollback behavior depends on the app deploy platform and database backup strategy. Capell can record upgrade state, but it cannot replace infrastructure-level rollback.

Use the upgrade runbook for package compatibility, migrations, cache clearing, and post-upgrade checks.

Marketplace

Marketplace account linking is the normal setup path. Public domain verification is only needed when Marketplace policy requires a stronger production trust signal.

Useful checks:

php artisan config:show capell-marketplace.marketplace.base_url
php artisan config:show capell-marketplace.marketplace.webhook_url
php artisan config:clear

The default Marketplace API URL is:

CAPELL_MARKETPLACE_URL=https://capell.app/api/v1

If verification fails, check the exact domain, public challenge URL, redirects/auth middleware/CDN rules, and the latest Marketplace registration row. Local hosts such as .test, .localhost, and 127.0.0.1 can be account-linked but cannot be publicly verified unless exposed through a real public hostname.

Use the Marketplace package overview for account connection, verification, heartbeat, cache, and install-authorization details. Use Troubleshooting for copy-paste checks.

For deeper Marketplace incidents, use Debugging Marketplace.

Common Fixes

`/admin` returns 403 or login loops

Run install/admin setup for the target user and clear caches:

php artisan capell:install [email protected]
php artisan optimize:clear

Dashboard loads but Capell resources are missing

php artisan optimize:clear
php artisan capell:admin-install

Published pages still show old content

php artisan optimize:clear
php artisan queue:work

If capell-app/html-cache is installed, rebuild or clear that package’s static output as well.

Frontend shows Laravel’s welcome page

Remove the default / route from routes/web.php, then clear route/config caches.

Non-interactive install fails with `Required.`

Pass all required prompt values:

php artisan capell:install \
  --no-interaction \
  --url=https://example.com \
  --name="Admin User" \
  [email protected] \
  --password="change-this-password"

Composer cannot find Capell packages

Check private repository/auth configuration:

composer config repositories
composer show capell-app/capell --available
composer clear-cache

Vite cannot resolve package CSS imports

Confirm the optional package command exists, then run the asset report/build path:

php artisan list capell
npm install
npm run build

For symlinked local packages, add a narrow Vite alias only when the dependency cannot be resolved normally.