Skip to main content

FAQs

How to know which ahoy commands are available?​

ahoy help

How to pass CLI arguments to commands?​

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

How to clear Drupal cache?​

ahoy drush cr

How to login to a Drupal site?​

ahoy login

How to connect to the database?​

If you have Sequel Ace:

ahoy db

Otherwise:

  1. Run ahoy info and grab the DB host port number.
  2. Use the connection details below.

Connection details:

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

How to use Xdebug?​

  1. Run ahoy debug.
  2. Enable listening for incoming debug connections in your IDE.
  3. If required, provide server URL to your IDE as it appears in the browser.
  4. Enable Xdebug flag in the request coming from your web browser (use one of the extensions or add ?XDEBUG_SESSION_START=1 to your URL).
  5. Set a breakpoint in your IDE and perform a request in the web browser.

Use the same commands to debug CLI scripts.

To disable, run ahoy up.

➡️ See Debugging

How to use Xdebug with Behat?​

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

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

Provided that your stack is already running:

  1. Switch to your branch
  2. composer install
  3. ahoy provision

You do not need to rebuild the full stack using ahoy build every time you switch branches. ahoy provision will update the environment to match the current branch.

However, sometimes you would want to have an absolutely clean environment - in that case, use ahoy build.

How to just import a database?​

Provided that your stack is already running:

ahoy import-db
ahoy import-db .data/db_custom.sql

How to add Drupal modules​

ahoy composer require drupal/module_name

How to add patches for Drupal modules​

  1. Add title to patch on https://drupal.org to the patches array in extra section in composer.json.

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

  2. Run

ahoy composer require drupal/somepackage

➡️ See Composer > Patching

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

Vortex does not block installation on security advisories by default, so composer install and composer update keep working. Advisories are surfaced by composer audit, which runs locally and in the CI lint job. When one appears:

  1. Update the affected package: try a newer version that resolves the advisory: composer update vendor/package-name.
  2. Review the advisory: run composer audit for details and assess whether it affects your project.
  3. Record an assessed exception: if no fixed version is available yet, or the vulnerability doesn't affect your use case, add the advisory to the config.policy.advisories.ignore-id list in your composer.json with a documented reason.
  4. Bypass CI for a known issue: set VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE to 1 to let CI pass while the advisory is being addressed.

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

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

This theme will be used when Drupal is in maintenance mode. If DRUPAL_MAINTENANCE_THEME is not set, the system will fall back to using the value of DRUPAL_THEME.

The maintenance theme should be a valid Drupal theme that is already installed and enabled on your site.

Behat tests with @javascript tag sometimes get stuck​

Behat tests with @javascript tag sometimes get stuck for about 10min then fail. The Chrome container randomly gets stuck for an unknown reason.

Restart the Chrome container: docker compose restart chrome