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. It prints a fix for most failures, and it prints a system report for support requests.

Doctor is 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 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.

Check the stack​

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 (Doctor skips this check 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 available inside the CLI container. Doctor first checks that the key is loaded in Pygmy's agent and that the agent's volume is mounted into the container. Either problem 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 bootstrap check when the variable is empty.
  7. Bootstrap - the home page HTML contains charset=, a sign that the Drupal site bootstrapped. The bootstrap check 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 an SSH warning 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 a command is missing. Doctor runs this command check even with the tools check turned off, and for ahoy doctor info too. As a result, the tools check always passes when it runs.

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 the check variables:

  • VORTEX_DOCTOR_CHECK_MINIMAL=1 - turns off the port, Pygmy, SSH, webserver and bootstrap checks, even when their own variables are 1. The tools and containers checks still follow their own variables. This preset 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, to validate a machine before the stack is up. With this preset, a check variable you set yourself still wins.

To print the system report, run the following command:

ahoy doctor info

Attach the report 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 the following, but only in the binary paths and the docker info output:

  • Your username
  • 36-character ID: values
  • Hex strings of 40 or more characters
  • IPv4 addresses

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.