Skip to main content
Version: v1

FAQs

This page answers the questions teams ask while they decide whether to adopt Vortex, including the trade-offs. For day-to-day questions inside a project, such as clearing caches, using Xdebug or adding modules and patches, see the Development FAQs.

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 in CI but fail at release time and block your deployment. Then you maintain the whole setup across every project you run.

Vortex ships those pieces already wired together and tested. You can override anything in your project and keep receiving updates, though each update replaces the files the template ships and you re-apply your overrides from .logs/vortex-update.md. 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, if you 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 them 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, if you 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. 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. You can disable or remove any feature. You maintain those changes yourself: 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. 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 to fix. 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 and replaces the files the template ships. When your README.md still carries the Vortex badge, the update records the project changes it overwrote in .logs/vortex-update.md. Each such update adds a section to that file, with 1 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, 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 the installer when you create a project. ahoy update-vortex runs it again on every update, with the answers it reads from your project.