Skip to main content
Version: v1

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 preceding step

➡️ 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?​

If your stack is already running:

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

You don't need to rebuild the full stack using ahoy build every time you switch branches. ahoy provision updates the environment to match the current branch.

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

➡️ See Environment > Switching branches

How to import a database without running updates?​

If 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 doesn't 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. 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. To let CI pass while the advisory is being addressed, set VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE to 1.

➡️ 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 against the root and the theme dependency trees, failing on advisories rated high or higher. When one appears:

  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 audit-ci.jsonc with notes and an expiry date.
  5. To let CI pass while the advisory is being addressed, set VORTEX_CI_NPM_AUDIT_IGNORE_FAILURE to 1.

➡️ 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 when it's in maintenance mode. If DRUPAL_MAINTENANCE_THEME isn't set, the system falls back to using the value of DRUPAL_THEME.

The maintenance theme should be 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​

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

Restart the Chrome container: docker compose restart chrome

➡️ See Testing > Behat