Logs and health checks for Vulpy Commerce

Tail environment logs, run health checks, and diagnose Fox from the host with pnpm vulpy env logs, verify, and hermes doctor.

Vulpy Commerce gives you host-level commands to tail logs, check service status, and diagnose the full stack. Use these tools to confirm an environment is healthy after a deploy or to trace a failure.

Ask Fox to read the logs for you. Fox tails and summarizes; you don’t need to grep through Docker output yourself.

Try prompts like:

• “Tail dev logs and summarize errors.”
• “Explain what pnpm vulpy verify checks.”
• “Why did verify fail?”

Environment logs

Tail the combined logs for every service in an environment:

pnpm vulpy env logs <name>

This streams logs from the storefront, Medusa, Postgres, Redis, and Matomo containers. Replace <name> with the environment you want to inspect, such as dev or staging.

Pipe the output through less for a paginated tail, or grep for a specific error keyword:

pnpm vulpy env logs staging | grep -i error

Environment status

Show the running state and health of each service in an environment:

pnpm vulpy env status <name>

Use this after pnpm vulpy env up <name> to confirm every container reached a healthy state.

Verify command

Run a broad health check across the stack:

pnpm vulpy verify

verify checks:

• Storefront responds
• Medusa API responds
• Payload seed markers are present
• Fox basic auth is configured

Run this after any upgrade or configuration change.

Fox diagnostics

Fox has its own doctor command that checks sidecar and host-level locks:

pnpm vulpy hermes doctor

This reports:

• Tailscale sidecar health
• Host egress lock status
• IMDS lock status on AWS

For details on the IMDS lock, see IMDS lock.

Where logs are stored

Logs are written to Docker per-container logs. You can rotate them via the Docker daemon configuration on the host. If disk usage grows, check Docker log settings and set a max size or max file count.

Live health probes

On a live environment, Caddy checks upstreams before routing traffic. Medusa exposes a health endpoint under its API, and Payload health is checked via the Next.js server. If an upstream fails its probe, Caddy stops sending traffic to it until it recovers.

Diagnose a failure

1. Tail logs during the change

   Run pnpm vulpy env logs <name> in one terminal while you restart or upgrade in another.

2. Run verify

   After the change, run pnpm vulpy verify to see which check fails.

3. Inspect the failing service

   If verify reports a storefront or Medusa failure, grep the logs for that service name and look for the first error after startup.

Matomo verification is a separate script: pnpm deploy:matomo:verify. This is the gate that pnpm vulpy env golive live uses before promoting an environment to live. Run it manually if you are debugging Matomo tracking issues.

Backup and restore

Take a backup before troubleshooting so you can roll back if needed.

Troubleshooting

Common errors, fixes, and where to look next.