Skip to main content
Version: v1

Doctor

Doctor checks your machine and the local stack layer by layer, from the installed tools up to the Drupal site, and prints a fix for most problems it finds. It also prints a system report for support requests. It's a shell script, vendor/bin/vortex-doctor, shipped in the drevops/vortex-tooling Composer package. It runs on your host, outside the containers, so it can still report on a stack that won't start.

This page is for developers whose local stack misbehaves and for anyone preparing a support request. It lists what each check verifies, how to choose which checks run, and what the system report contains.

Checking project status​

Run Doctor with the following command:

ahoy doctor

Without Ahoy, run ./vendor/bin/vortex-doctor from the project root. The ahoy command must still be installed, because Doctor requires it on every run.

Doctor runs its checks in order, reports each one on its own line, and stops at the first check that fails.

Expand to see the ahoy doctor video

Doctor runs these checks, in this order:

  1. Tools - the docker, pygmy, and ahoy commands are installed.
  2. Port - port 80 on the host is either free or held by Docker (skipped on Linux).
  3. Pygmy - all 4 Pygmy services are running: the SSH agent, the mail catcher, the proxy, and the DNS server. For the container names Doctor looks for, see Pygmy.
  4. Containers - the cli, php, nginx, and database containers are running.
  5. SSH - the SSH key is loaded in Pygmy's agent, the agent's volume is mounted into the CLI container, and the key is available inside it. A missing key in the agent or a missing mount prints a warning with the fix. The check fails only when both are in place and the key still isn't available in the container.
  6. Webserver - the web server answers at the local development URL with HTTP status 200 or 403. Doctor reads the URL from LOCALDEV_URL in the CLI container, and skips this check and the next one when it's empty.
  7. Bootstrap - the home page HTML contains charset=, a sign that the Drupal site bootstrapped. It runs only as part of the webserver check.

When every check that runs passes, Doctor ends with [ OK ] All required checks have passed. A check that's turned off or skipped prints nothing. An SSH warning isn't a failure, so a run with one still ends with that line.

Before the first check, Doctor makes sure the docker, pygmy, and ahoy commands exist, and stops with Command <name> is not available. if one doesn't. That happens even with the tools check turned off, and for ahoy doctor info too. The tools check looks for the same 3 commands, so when it runs, it passes.

A failing check prints what to do about it, for example:

[FAIL] Pygmy service amazeeio-haproxy is not running. Run 'pygmy up' or 'pygmy restart' to fix.

Configuration​

Each check has its own variable: 0 skips the check and 1 runs it. All 7 default to 1:

  • VORTEX_DOCTOR_CHECK_TOOLS - the tools check
  • VORTEX_DOCTOR_CHECK_PORT - the port check
  • VORTEX_DOCTOR_CHECK_PYGMY - the Pygmy check
  • VORTEX_DOCTOR_CHECK_CONTAINERS - the containers check
  • VORTEX_DOCTOR_CHECK_SSH - the SSH check
  • VORTEX_DOCTOR_CHECK_WEBSERVER - the webserver check
  • VORTEX_DOCTOR_CHECK_BOOTSTRAP - the bootstrap check

The bootstrap check runs inside the webserver check, so VORTEX_DOCTOR_CHECK_WEBSERVER=0 skips both. Set the variables in .env.local, or in front of the command, as in VORTEX_DOCTOR_CHECK_PORT=0 ahoy doctor.

VORTEX_SSH_FILE sets the key the SSH check looks for in Pygmy's agent. It defaults to ${HOME}/.ssh/id_rsa.

2 presets combine them:

  • VORTEX_DOCTOR_CHECK_MINIMAL=1 - turns off the port, Pygmy, SSH, webserver, and bootstrap checks, even when their own variables are set to 1. The tools and containers checks still follow their own variables. This suits environments without running Pygmy services or a routable local URL, such as CI.
  • VORTEX_DOCTOR_CHECK_PREFLIGHT=1 - turns the tools, port, and Pygmy checks on and the rest off, for validating a machine before the stack is up. A check variable you set yourself still overrides this preset.

Getting system information​

To print the system report, run the following command:

ahoy doctor info

ahoy doctor info prints a report to attach to a support request. It covers the following:

  • The operating system version
  • The path and version of the Docker, Pygmy, and Ahoy binaries
  • The Docker daemon details from docker info
  • The version of the Docker Compose V2 plugin, docker compose
  • The path and version of the legacy Docker Compose V1 binary, docker-compose

Doctor redacts your username, 36-character ID: values, hex strings of 40 or more characters, and IPv4 addresses, but only in the binary paths and the docker info output. Everything else stays as printed, such as the host name that docker info reports, so read the report before you share it.

Expand to see the ahoy doctor info video

➡️ See Support for how to report an issue.