Skip to main content
Version: v1

FAQs

These are the questions teams ask while deciding whether to adopt Vortex, with straight answers, trade-offs included. After you start working in a project, the Development FAQs cover the day-to-day questions, such as clearing caches, using Xdebug, or adding modules and patches.

Why use Vortex instead of the Drupal Composer template?​

The Drupal Composer template gives you a starting point, but you still need to add everything else:

  • CI pipelines
  • Tooling and automations
  • Deployment scripts
  • Hosting configurations
  • Documentation

Then you need to test that everything works together correctly.

You also need to watch for false negatives: faulty tests that pass silently in CI but fail at release time and block your deployment. And you need to maintain all this across every project you run.

Vortex ships those pieces already wired together and tested. You can override anything in your project and still receive future updates, though you re-apply your changes to the files each update replaces. Your team gets the same documentation and tooling on every project.

Can I use Vortex with an existing project?​

Yes. You install Vortex into a clean working copy, then merge your project back into it. See Installation for the steps.

Can I keep my existing CI provider?​

Yes, but you'll need to update your CI configuration to call the Vortex scripts. Vortex ships ready-made configurations for GitHub Actions and CircleCI only, in .github/workflows/build-test-deploy.yml and .circleci/config.yml, so use those as the reference for which scripts to run and in what order.

In those configurations, each job installs the scripts with ./scripts/vortex-tooling.sh, then calls them from vendor/bin/ in this order:

  • Database - vortex-fetch-db, then vortex-provision with VORTEX_PROVISION_POST_OPERATIONS_SKIP=1, then vortex-export-db
  • Build - vortex-provision, then the tests, then vortex-check-worktree-changes
  • Deploy - vortex-deploy, with VORTEX_DEPLOY_MODE=tag for a tag

Continuous integration explains what each job does.

Can I keep my existing hosting?​

Yes, but you'll need to adapt the deployment to your hosting provider. Outside Acquia and Lagoon, the artifact deployment type pushes the built code to a Git repository your host deploys from. The webhook type calls a URL that starts your host's deployment instead. See Artifact deployment and Webhook deployment for the setup.

Can I change things I don't like?​

Yes. Vortex is a template, so every file it gives you is yours to change, and you can disable or remove any feature. You maintain those changes yourself, though: each update replaces the files the template ships, and you re-apply your changes from .logs/vortex-update.md.

If you disagree with a decision in Vortex, open an issue and let's talk it through.

Isn't this overkill for my project?​

Vortex offers its full feature set to every project, whatever its size, but you don't have to take everything. The installer asks about each feature, so you install only the ones you want.

If you're sure you don't need what it offers, Vortex might not be the right fit, and that's fine.

Isn't this too opinionated?​

Vortex is opinionated where it has to be for everything to work together. You can customize many things, but some defaults exist to keep the tools compatible with each other.

If something feels unreasonably opinionated, we treat that as a defect and we'd like to fix it. Tell us in the issue queue.

How hard is it to upgrade?​

The update itself is 1 command, ahoy update-vortex, which pulls in the latest Vortex release for your major version. It replaces the files the template ships and records the project changes it overwrote in .logs/vortex-update.md, as long as your README.md still carries the Vortex badge. An update that overwrites your changes adds a section to that file, with an entry per file that usually holds 2 diffs: your change and the change the update brings. Re-applying those changes and reviewing the diff is the manual part, much like merging changes between projects.

That manual work is the trade-off of building on an upgradable project template instead of a dependency package. With a template, you have full control. With a package, someone else has full control of the code that drives your project. Vortex already takes the package route for its scripts: they ship as the drevops/vortex-tooling Composer package and update through Composer. The template requires it as ~1.5.0, so composer update picks up only 1.5.x patch releases. A newer minor version arrives when ahoy update-vortex brings a composer.json with a raised constraint.

Near the end, the update shows a Finished updating Vortex box. If it shows Finished installing Vortex instead, the update didn't find the Vortex badge in README.md and recorded nothing. Updating Vortex covers the full procedure.

How easy is it to choose the features that I need?​

The installer walks you through the features prompt by prompt and installs only the ones you pick. You run it when you create a project, and ahoy update-vortex runs it again on every update with the answers it finds in your project.