# 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](site-health.md) 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:

```bash
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](upgrading.md) 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:

```bash
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:

```ini
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](../../packages/marketplace/docs/overview.md) for account connection, verification, heartbeat, cache, and install-authorization details. Use [Troubleshooting](troubleshooting.md) for copy-paste checks.

For deeper Marketplace incidents, use [Debugging Marketplace](debugging-marketplace.md).

## Common Fixes

### `/admin` returns 403 or login loops

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

```bash
php artisan capell:install --user=you@example.com
php artisan optimize:clear
```

### Dashboard loads but Capell resources are missing

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

### Published pages still show old content

```bash
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:

```bash
php artisan capell:install \
  --no-interaction \
  --url=https://example.com \
  --name="Admin User" \
  --email=admin@example.com \
  --password="change-this-password"
```

### Composer cannot find Capell packages

Check private repository/auth configuration:

```bash
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:

```bash
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.