Development
Typical development process
- Pull the latest changes from the remote repository.
- Fetch the latest database dump from the production environment.
- Build the project.
- Start a new feature or bugfix branch:
- Create a new branch from
develop. - Implement the feature or fix the bug.
- Create a new branch from
- Run tests:
- Run automated tests locally.
- Fix any failing tests.
- Run code quality checks:
- Run static code analysis locally.
- Fix any issues reported.
- Commit changes to the branch and push it to the remote repository.
- Create a pull request:
- Create a pull request from the branch to
develop. - Assign reviewers.
- Wait for the continuous integration pipeline to pass.
- Create a pull request from the branch to
Common commands
The most common day-to-day commands. Each video is a live recording captured on
a fresh Vortex project; re-record them with ahoy update-videos.
Build the project
Build
ahoy build
Re-provision the site
Provision
ahoy provision
Run linters
Lint
ahoy lint
Run unit, kernel and functional tests
Test
ahoy test
Run BDD tests
Test BDD
ahoy test-bdd
Running CLI commands
You can run CLI commands inside the project containers.
- Ahoy
- Docker Compose
# Run a command in the CLI container
ahoy cli echo "Hello, World!"
# SSH into the CLI container
ahoy cli
# 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
- Docker Compose
# Run Drush command
ahoy drush status
# Run Composer command
ahoy composer install
# 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
- Docker Compose
# 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
# 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 ./vendor/drevops/vortex-tooling/src/provision
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
- Docker Compose
# Reset local environment
ahoy reset
# Fully reset repository to a state as if it was just cloned
ahoy reset hard
# Reset local environment
docker compose down
./vendor/drevops/vortex-tooling/src/reset
# Fully reset repository to a state as if it was just cloned
docker compose down
./vendor/drevops/vortex-tooling/src/reset hard
Environment variables
To update environment variables in your local development environment:
- Edit variables in
.env.localfile - Apply changes by restarting containers:
- Ahoy
- Docker Compose
ahoy restart
docker compose up -d
➡️ See Variables for comprehensive variable reference.
Performance optimization
- Ahoy
- Docker Compose
# 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
# 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
- Docker Compose
ahoy doctor # Check for common issues
ahoy down && ahoy up # Restart containers
ahoy info # Verify URLs and ports
./vendor/drevops/vortex-tooling/src/doctor # Check for common issues
docker compose down && docker compose up -d # Restart containers
docker compose exec cli ./vendor/drevops/vortex-tooling/src/info # Verify URLs and ports
Database connection errors
- Ahoy
- Docker Compose
docker compose ps # Check if database container is running
ahoy reset # Nuclear option: rebuild everything
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
- Docker Compose
# Increase PHP memory temporarily
ahoy composer install --no-dev --optimize-autoloader
# Increase PHP memory temporarily
docker compose exec cli composer install --no-dev --optimize-autoloader
Log files
- Ahoy
- Docker Compose
# View ahoy logs
ahoy logs
# Check container logs
docker compose logs --tail=50 cli
# View Drupal watchdog logs
ahoy drush watchdog:show --count=20
# 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
Local Development
═══════════════════════════════════════ ══════════════════════════════════════════════════
Developer writes code ──► Build and test locally ──► Commit changes
│
▼
Git Repository
═════════════════════════════════════════════════════════════════════════════════════════
Push to remote branch ──► Open/Update Pull Request
│
▼
┌─ CI Pipeline ──────────────────────────────────────────────────────────────────────────────┐
│ │
│ The Lint, Test and Build jobs run in parallel. Deployment runs after all three pass. │
│ │
│ Lint Job │
│ Build CLI container ──► Composer validate / audit / normalize ──► Hadolint ──► │
│ DCLint ──► PHPCS ──► PHPStan ──► Rector ──► Twig CS Fixer ──► │
│ Gherkin Lint ──► ESLint / Stylelint │
│ │
│ Test Job │
│ Restore the database cache. On the first build of the day (cache miss), each runner │
│ downloads the production database and exports a clean pre-provision dump; only the │
│ primary runner stores it in the cache for the rest of the day's builds. │
│ ▼ │
│ Build Docker ──► Composer deps ──► NPM deps ──► Assets │
│ ▼ │
│ Import cached database ──► drush deploy ──► custom deploy steps │
│ ▼ │
│ PHPUnit tests ──► Behat tests │
│ │
│ Build Job │
│ Assemble and validate the deployable artifact │
│ │
│ Deployment Job (after Lint, Test and Build pass) │
│ Webhook URL ──► artifact package ──► Lagoon webhook ──► Docker container image │
│ │
└────────────────────────────────────────────────────────────────────────────────────────────┘
│
▼
Hosting Platform
═════════════════════════════════════════════════════════════════════════════════════════
◆ Environment ──No──► Sync DB from production ───┐
exists? │
│ Yes ▼
└──────────────────────────────────► drush deploy ──► Custom scripts ──► Notifications
Available Environments
═════════════════════════════════════════════════════════════════════════════════════════
┊ PR Environment ┊ Dev Staging Production
┊ (auto-removed) ┊ develop branch main branch production branch or tag
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 |