Skip to main content
Version: v1

FAQs

This page answers the questions that developers ask most often while they work on a Vortex project, from running commands to recovering a stuck test. Each answer links to the page that covers its topic in full.

How to know which ahoy commands are available?​

To list the commands with their descriptions, run the following command:

ahoy help

➡️ See Environment > Ahoy

How to pass CLI arguments to commands?​

Add the arguments after the command name. The -- separator is optional, because Ahoy removes it before it runs the command:

ahoy mycommand -- myarg1 myarg2 --myoption1 --myoption2=myvalue

➡️ See Environment > Ahoy

How to clear Drupal cache?​

To rebuild the Drupal caches, run the following command:

ahoy drush cr

➡️ See Environment > Drush

How to login to a Drupal site?​

To unblock user 1 and print a one-time login link for it, run the following command:

ahoy login

➡️ See Environment > Drush

How to connect to the database?​

To connect, first get the port that the database uses on your host:

On macOS with Sequel Ace installed, open the database in it:

ahoy db

Otherwise, follow these steps:

  1. Run ahoy info, which prints the port as DB port on host.
  2. Use the following connection details.

Connect with these details:

  • Host: 127.0.0.1
  • Username: drupal
  • Password: drupal
  • Database: drupal
  • Port: the port from the preceding step

➡️ See Environment > Docker

How to use Xdebug?​

Turn Xdebug on in the containers, then start a debug session from your IDE:

  1. Run ahoy debug. After php -v in the CLI container confirms that Xdebug loaded, it prints Enabled debug configuration. Use 'ahoy up' to disable. To check the state later, run ahoy info: its Xdebug line reads Enabled ('ahoy up cli' to disable) while Xdebug is on.
  2. Turn on listening for incoming debug connections in your IDE.
  3. If your IDE asks for a server URL, give it the URL as it appears in the browser.
  4. Turn on the Xdebug flag in the requests from your browser, with one of the extensions or by adding ?XDEBUG_SESSION_START=1 to the URL.
  5. Set a breakpoint in your IDE and load the page in your browser.

Use the same commands to debug CLI scripts.

To turn Xdebug off, run ahoy up. The ahoy info line suggests ahoy up cli instead, but that recreates only the cli container, so web requests still run with Xdebug in the php container.

➡️ See Environment > Debugging

How to use Xdebug with Behat?​

Turn Xdebug on, then run Behat with the --xdebug flag inside the CLI container:

  1. Enable debugging: ahoy debug
  2. Enter CLI container: ahoy cli
  3. Run Behat tests:
vendor/bin/behat --xdebug path/to/test.feature

Behat restarts itself without Xdebug unless you pass --xdebug or a debug session is already active.

➡️ See Environment > Debugging and Testing > Behat

What should I do to switch to a "clean" branch environment?​

If your stack is already running, follow these steps:

  1. Switch to your branch.
  2. Run ahoy composer install.
  3. If the branch changes theme files, run ahoy fe.
  4. Run ahoy provision.

You don't need to rebuild the full stack with ahoy build every time you switch branches. ahoy provision updates the environment to match the current branch, applying its database updates and configuration.

ahoy provision asks you to confirm first. It then keeps an existing site's database, because .env sets VORTEX_PROVISION_OVERRIDE_DB to 0. It replaces the database only when that variable is 1, as .env.local.example sets it, or when VORTEX_DB_IMAGE is set, in which case it reloads the database container from that image first. To see which applies to you, check both variables in .env.local too: a value there overrides the one in .env.

When you need a fully clean environment, use ahoy build.

➡️ See Environment > Switching branches

How to import a database without running updates?​

The import drops the current database and loads the dump without running database updates or importing configuration. If your stack is already running, pick the command for your dump file:

Import from the default dump file at .data/db.sql:

ahoy import-db

Import from a specific dump file:

ahoy import-db .data/db_custom.sql

ahoy import-db asks you to confirm before it replaces the database. Confirm that the output ends with Finished database import.

➡️ See Provision > Database

How to add Drupal modules?​

To add a module's code to the project, require it with Composer:

ahoy composer require drupal/module_name

Then install the module with the drush pm:install command, and export the configuration with drush config:export, so the next configuration import keeps the module installed.

➡️ See Composer > Installing and Modules

How to add patches for Drupal modules?​

To patch a module, follow these steps:

  1. Add the patch to extra.patches in composer.json, under the package's name, with the patch description as the key and the patch URL or local path as the value:

    "extra": {
        "patches": {
            "drupal/somepackage": {
                "Remote patch description": "https://www.drupal.org/files/issues/issue.patch",
                "Local patch description": "patches/package-description.patch"
            }
        }
    }

  2. Regenerate the patches lock file, re-apply the patches, and update composer.lock:

ahoy composer patches-relock
ahoy composer patches-repatch
ahoy composer update --lock

Confirm that the patches-repatch output has a - Patching line with the name of the patched package.

➡️ See Composer > Patching for the full patching workflow, including removing patches.

What should I do when composer audit reports a security vulnerability?​

Vortex sets config.policy.advisories.block to false in composer.json, so security advisories don't block composer update, composer require, or composer remove. composer install installs exactly what the lock file pins, so advisories never block it. composer audit reports the advisories instead, both when you run it locally and in the CI security audit workflow. When it reports one, follow these steps:

  1. Try updating the affected package to a newer version that resolves the advisory: composer update vendor/package-name.
  2. Run composer audit to review the advisory details and assess whether it affects your project.
  3. If no fixed version exists yet, or the vulnerability doesn't affect your use case, add the advisory to the config.policy.advisories.ignore-id list in composer.json with a documented reason.
  4. Optional: To let CI pass while you address the advisory, set VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE to 1, as a repository variable on GitHub Actions or as an environment variable in the CircleCI project settings.

➡️ See Security > Dependency audit for the full config.policy reference and guidance on choosing the right settings for your project.

What should I do when npm audit reports a security vulnerability?​

The CI security audit workflow runs npm audit through audit-ci against the root and the custom theme's dependency trees, and fails on advisories rated high or higher. The Audit npm packages step checks the root, and Audit npm packages of the theme checks the theme in web/themes/custom/your_site_theme. When a step reports an advisory, follow these steps in the directory it checks:

  1. Try updating the affected package to a newer version that resolves the advisory: npm update <package-name>.
  2. Run npm audit to review the advisory details, including which direct dependency pulls the affected package in, and assess whether it affects your project.
  3. When the affected package isn't a direct dependency, pin a patched version of it with an overrides entry in package.json, then run npm install.
  4. If no fixed version exists or the vulnerability doesn't affect you, add it to the allowlist in that directory's package-audit.jsonc, with notes and an expiry date. The root and theme files each apply only to their own tree.
  5. Optional: To let CI pass while you address the advisory, set VORTEX_CI_NPM_AUDIT_IGNORE_FAILURE to 1, as a repository variable on GitHub Actions or as an environment variable in the CircleCI project settings.

➡️ See Security > Dependency audit for the severity threshold, the overrides mechanism, and the allowlist format.

How to set a custom maintenance theme?​

To set a custom theme for Drupal's maintenance mode (when the site is offline for updates), set the DRUPAL_MAINTENANCE_THEME environment variable:

# In .env file
DRUPAL_MAINTENANCE_THEME=my_custom_theme

Drupal uses this theme while the site is in maintenance mode. The installer sets it in .env to the theme you chose for the site. When DRUPAL_MAINTENANCE_THEME isn't set, settings.php falls back to the value of DRUPAL_THEME, and to Claro when neither is set.

Use a valid Drupal theme that's already installed and enabled on your site.

➡️ See Environment > Environment variables

Behat tests with @javascript tag sometimes get stuck​

A scenario tagged @javascript sometimes hangs and then fails, because the Chrome container stops responding. It happens at random, and its cause is unknown. To recover:

  • Restart the Chrome container with docker compose restart chrome, or with ahoy restart chrome.

Confirm that the scenario passes when you run the Behat tests again.

➡️ See Testing > Behat