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
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 ./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
- 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
./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:
- 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
./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
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 ────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─ Database Job (Nightly) ───────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Scheduled ──► Download production ──► Sanitize database ──► Store database cache │ │
│ │ trigger database Remove sensitive data │ │
│ │ │ │
│ └─────────────────────────────────────┬──────────────────────────────────────────────┘ │
│ │ Provides cached database │
│ ▼ │
│ ┌─ Lint Job ────────────┐ ┌─ Database Job ──────────────────────────────────────────┐ │
│ │ │ │ │ │
│ │ Build CLI container │ │ ◆ Nightly cache ──Yes──► Pipeline Success │ │
│ │ ▼ │ │ exists? │ │
│ │ Composer validate │ │ │ No │ │
│ │ ▼ │ │ ▼ │ │
│ │ Composer audit │ │ Download ──► Sanitize ──► Store database │ │
│ │ ▼ │ │ production database cache │ │
│ │ Composer normalize │ │ database Remove │ │
│ │ ▼ │ │ sensitive data │ │
│ │ Hadolint │ │ │ │
│ │ ▼ │ └───────────────────────────┬─────────────────────────────┘ │
│ │ DCLint │ │ │
│ │ ▼ │ ▼ │
│ │ PHPCS │ ┌─ Build Job ────────────────────────────────────────────┐ │
│ │ ▼ │ │ │ │
│ │ PHPStan │ │ Code assembly │ │
│ │ ▼ │ │ Build Docker ──► Composer deps ──► NPM deps ──► Assets│ │
│ │ Rector │ │ │ │ │
│ │ ▼ │ │ ▼ │ │
│ │ PHPMD │ │ Website setup │ │
│ │ ▼ │ │ Import cached DB ──► drush deploy ──► Custom scripts │ │
│ │ Twig CS Fixer │ │ │ │ │
│ │ ▼ │ │ ▼ │ │
│ │ Gherkin Lint │ │ Testing │ │
│ │ ▼ │ │ PHPUnit tests ──► Behat tests │ │
│ │ ESLint / Stylelint │ │ │ │
│ │ │ └────────────────────────────┬───────────────────────────┘ │
│ └──────────┬────────────┘ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─ Deployment Job ─────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Webhook Artifact Lagoon Docker │ │
│ │ Call URL Package artifact Call Lagoon webhook Create 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 |