Ensuring Ghost CMS Operational Health with `ghost doctor`

Ghost CMS Health Check: Immediate Operational Status

If your Ghost CMS instance is exhibiting unexpected behavior—such as failing to publish content, slow response times, or failing to start—the immediate takeaway is to run ghost doctor via the Ghost CLI. This tool aggregates system diagnostics, pointing directly to configuration errors, database connectivity issues, or missing dependencies rather than requiring manual log parsing.

Prerequisites for Diagnosis

• Node.js environment installed (Ghost typically requires a specific LTS version).
• Ghost CLI installed globally or locally within the installation directory.
• Access to the server shell where Ghost is running.

Procedure: Running the System Diagnostic

Execute the following command in the root directory of your Ghost installation:

ghost doctor

Permissions: Requires read/execute access to the installation directory. Expected Check: The output will list checks (e.g., database connection, Node version, required packages) with a clear PASS/FAIL status for each.

Interpreting Diagnostic Failures

If ghost doctor reports a failure, the output is specific. For example, if the database check fails, it indicates a connection string error (e.g., incorrect hostname or credentials) in the Ghost configuration file, not a general application crash. If the Node version check fails, the environment needs updating to match Ghost's requirements.

Concrete Diagnostic Example

Suppose ghost doctor reports a failure related to the database connection. You must verify the connection parameters (host, user, password) within the Ghost configuration file (often config.production.json or environment variables, depending on deployment). A common error is using MySQL credentials when the instance is configured for Postgres.

Verification and Recovery

Practical Check: After addressing a reported issue (e.g., correcting a configuration file), run ghost doctor again. The relevant check must transition from FAIL to PASS. Recovery: If the failure is configuration-based, correct the file and restart the service using ghost restart. If the failure is environmental (e.g., missing dependency), run ghost setup or relevant installation commands, not just a restart.

Limitations

ghost doctor verifies configuration and environment health; it does not debug application logic errors within custom themes or plugins. Database migration failures require specific migration tool usage, not just a health check.