Skip to main content

Environment

The local environment is a Docker Compose stack built from Lagoon container images, with Ahoy wrapping the longer docker compose commands into short, memorable ones. This section covers every layer of that stack: Docker and the anatomy of docker-compose.yml, the shared services provided by Pygmy, the Doctor project checks, the Ahoy and Drush command wrappers, logs, debugging, and troubleshooting - each on its own page below. The day-to-day operations of switching branches, resetting, working with environment variables and ignored files stay on this page.

In this section​

PageWhat it covers
DockerThe container stack and the docker-compose.yml anatomy
PygmyThe shared proxy, DNS and mail catcher services
AhoyCommand shortcuts, configuration and running CLI commands
DoctorStack diagnostics and system information
DrushThe Drupal CLI, its configuration and aliases
LogsContainer logs
DebuggingXdebug, authenticated requests and container debugging
TroubleshootingCommon local stack failures and fixes

Ignored files​

Vortex manages three ignore files as deny lists: nothing is excluded by default, and each file lists only what must be kept out of its target. This is the opposite of an allow list, where everything is excluded by default and every addition has to be explicitly re-included. The deny-list model follows the "avoid silent errors" principle - a newly added file is visible by default instead of silently disappearing until someone remembers to allow it.

The .gitignore file controls which paths Git ignores in the project repository - committing a file is still what puts it there. It excludes Composer- and npm-generated directories (web/core, web/modules/contrib, vendor, node_modules), local setting overrides, caches, and content files. Two sections stay as small allow lists because a deny rule cannot express them:

  • recipes/ - Composer installs contributed recipes next to your custom ones, so each custom recipe is un-ignored explicitly.
  • .claude/ - Claude writes machine-local state here, so only .claude/settings.json and .claude/skills/ are un-ignored by default.

The other two ignore files apply the same deny-list model to different targets:

A new file or directory added to the project is subject to no exclusion: once committed, it is part of the repository, and it enters the image build and the deployment artifact automatically. Add an entry to one of these ignore files only when a file must be kept out of that particular target.

Switching branches​

When switching to a new branch, there is no need to rebuild the entire project as it may take a long time. Instead, you can run these commands as needed based on what changed:

# Update Composer dependencies (only if composer.json/composer.lock changed)
ahoy composer install
# Rebuild frontend assets (only if theme files changed)
ahoy fe
# Provision site (only if database or configuration changes expected)
ahoy provision

Resetting​

To reset the local environment, use the reset command. This will stop and remove all containers and downloaded dependency packages (vendor, node_modules etc.).

# Reset local environment
ahoy reset
# Fully reset repository to a state as if it was just cloned
ahoy reset --hard

Environment variables​

To update environment variables in your local development environment:

  1. Edit variables in .env.local file
  2. Apply changes by re-creating the containers (a plain restart does not re-read the .env files):
ahoy up

➡️ See Variables for the full variable reference.