Skip to main content

FAQs

How to know which ahoy commands are available?​

ahoy help

➡️ See Environment > Ahoy

How to pass CLI arguments to commands?​

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

➡️ See Environment > Ahoy

How to clear Drupal cache?​

ahoy drush cr

➡️ See Environment > Drush

How to login to a Drupal site?​

ahoy login

➡️ See Environment > Drush

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

➡️ See Environment > Docker

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 Environment > 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

➡️ See Environment > Debugging and Testing > Behat

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.

➡️ See Environment > Switching branches

How to import a database without running updates?​

Provided that your stack is already running:

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

➡️ See Provision > Database

How to add Drupal modules?​

ahoy composer require drupal/module_name

➡️ See Composer > Installing and Modules

How to add patches for Drupal modules?​

  1. Add the patch to the patches array in the extra section of composer.json, with the patch title as the key:

    "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 and re-apply the patches:

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

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

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 security audit workflow. 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 Security > Dependency audit 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.

➡️ See Environment > Environment variables

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

➡️ See Testing > Behat