Development

Typical development process

1. Pull the latest changes from the remote repository.
2. Fetch the latest database dump from the production environment.
3. Build the project.
4. Start a new feature or bugfix branch:
   • Create a new branch from develop.
   • Implement the feature or fix the bug.
5. Run tests:
   • Run automated tests locally.
   • Fix any failing tests.
6. Run code quality checks:
   • Run static code analysis locally.
   • Fix any issues reported.
7. Commit changes to the branch and push it to the remote repository.
8. Create a pull request:
   • Create a pull request from the branch to develop.
   • Assign reviewers.
   • Wait for the continuous integration pipeline to pass.

Running CLI commands

You can run CLI commands inside the project containers.

Ahoy

# Run a command in the CLI container
ahoy cli echo "Hello, World!"
# SSH into the CLI container
ahoy cli

Docker Compose

# Run a command in the CLI container
docker compose exec cli echo "Hello, World!"
# SSH into the CLI container
docker compose exec cli bash

You can also use shortcuts for common commands:

Ahoy

# Run Drush command
ahoy drush status
# Run Composer command
ahoy composer install

Docker Compose

# Run Drush command
docker compose exec cli drush status
# Run Composer command
docker compose exec cli composer install

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:

Ahoy

# 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

Docker Compose

# Update Composer dependencies (only if composer.json/composer.lock changed)
docker compose exec cli composer install
# Rebuild frontend assets (only if theme files changed)
docker compose exec cli bash -c "cd \${WEBROOT}/themes/custom/\${DRUPAL_THEME} && yarn run build"
# Provision site (only if database or configuration changes expected)
docker compose exec cli ./scripts/vortex/provision.sh

Resetting the codebase

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

Ahoy

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

Docker Compose

# Reset local environment
docker compose down
./scripts/vortex/reset.sh
# Fully reset repository to a state as if it was just cloned
docker compose down
./scripts/vortex/reset.sh hard

Environment variables

To update environment variables in your local development environment:

1. Edit variables in .env.local file
2. Apply changes by restarting containers:

Ahoy

ahoy restart

Docker Compose

docker compose up -d

➡️ See Variables for comprehensive variable reference.

Performance optimization

Ahoy

# Enable CSS/JS aggregation
ahoy drush config:set system.performance css.preprocess 1
ahoy drush config:set system.performance js.preprocess 1
# Clear render cache
ahoy drush cache:rebuild-external
# Check database updates needed
ahoy drush updatedb:status

Docker Compose

# Enable CSS/JS aggregation
docker compose exec cli drush config:set system.performance css.preprocess 1
docker compose exec cli drush config:set system.performance js.preprocess 1
# Clear render cache
docker compose exec cli drush cache:rebuild-external
# Check database updates needed
docker compose exec cli drush updatedb:status

Common issues & solutions

Site not loading

Ahoy

ahoy doctor                # Check for common issues
ahoy down && ahoy up       # Restart containers
ahoy info                  # Verify URLs and ports

Docker Compose

./scripts/vortex/doctor.sh                       # Check for common issues
docker compose down && docker compose up -d      # Restart containers
docker compose exec cli ./scripts/vortex/info.sh # Verify URLs and ports

Database connection errors

Ahoy

docker compose ps      # Check if database container is running
ahoy reset             # Nuclear option: rebuild everything

Docker Compose

docker compose ps      # Check if database container is running
docker compose down --volumes && docker compose up -d  # Nuclear option

Permission issues

# Fix file permissions (Linux/Mac)
sudo chown -R $USER:$USER .

Memory issues during composer install

Ahoy

# Increase PHP memory temporarily
ahoy composer install --no-dev --optimize-autoloader

Docker Compose

# Increase PHP memory temporarily
docker compose exec cli composer install --no-dev --optimize-autoloader

Log files

Ahoy

# View ahoy logs
ahoy logs
# Check container logs
docker compose logs --tail=50 cli
# View Drupal watchdog logs
ahoy drush watchdog:show --count=20

Docker Compose

# Check container logs
docker compose logs --tail=50 cli
# View Drupal watchdog logs
docker compose exec cli drush watchdog:show --count=20

Beyond local development

Expand to see the complete code lifecycle

See also

Topic	Description
Database	Fetching, refreshing, and exporting databases
Composer	Managing packages, patching, security auditing
Debugging	Xdebug, curl testing, container access
PHPUnit	Unit, Kernel, and Functional testing
Behat	Behavior-Driven Development (BDD) testing