Skip to main content
Version: v1

Updating Vortex

This page is for developers who maintain a project built from Vortex and want to bring in a newer Vortex release. It explains what an update changes, then takes you from a fresh branch to a production release. To install Vortex for the first time, see Installation instead.

You can keep updating your project long after the initial setup, to pick up each release's features and bug fixes. The update replaces the files the template ships, but it records every customization it overwrites, so you can re-apply each one.

Overview​

Updating Vortex gives existing projects the following:

  • Security patches and bug fixes
  • New features and improvements
  • Updated dependencies and tooling
  • Deployment improvements

ahoy update-vortex runs the Vortex installer against your project without prompts. The installer reads the answers it needs from your project, such as the names, services and hosting provider, and reapplies them to the release it downloads. After the update, review the changes and commit them to your project.

Staying on your major version

ahoy update-vortex updates your project within its current major version. It downloads the installer from its major's own path, /v1/install on the 1.x line. A 1.x project therefore receives the latest 1.x release and never moves to 2.x on its own.

The installer also stops at a major boundary. When you run it against a project from another major, it exits with an error that names the installer for that project's major. There's no automated migration from 1.x to 2.x.

Before updating​

Check the following before you run the update:

  • Ahoy, php, curl, git, tar and composer are available on your machine, because the update runs outside the containers. Its script stops with Command php is not available. or Command curl is not available. when 1 of those is missing. The installer it runs stops with a Missing required command error when git, tar or composer is missing.
  • The project's containers are running, started with ahoy up, because step 7 runs Composer inside the cli container. On your machine, the stack needs Docker and a running Pygmy.
  • The Vortex badge is still in your project's README.md. The update reads the version your project runs from the badge. Without it, the installer treats your project as a new installation and records none of the customizations it overwrites.
  • Your working tree has no uncommitted changes, so the diff after the update holds only what the update changed.

Read the release notes for every version between yours and the target. Look for breaking changes that affect your project, and for environment variables that were added or changed, because your CI and hosting environments might need the new values.

Update process​

Run the update on its own branch, then take it through review, CI and deployment like any other change:

  1. Create a new branch for the update:

    Create a new branch for the update
    git checkout -b update-vortex

  2. Run the update command:

    Update to the latest version
    ahoy update-vortex

    Near the end, the update shows Finished updating Vortex with a reminder to review and commit the changes. When it replaced any of your changes, it also names .logs/vortex-update.md, the file that records them.

    To pin a specific release or commit instead, pass the repository URL with the reference after #:

    Update to a specific version
    ahoy update-vortex https://github.com/drevops/vortex.git#1.2.3

    ahoy update-vortex https://github.com/drevops/vortex.git#abcd123

    To review or change the answers the update reapplies, run ahoy update-vortex --interactive.

  3. Review the changes the update made:

    Review changes
    git status
    git diff

  4. Re-apply your customizations from .logs/vortex-update.md, and delete each entry after you've resolved it. Each entry shows 2 diffs: your change and the change the new version brings. Each update appends a new section to the file. Git ignores the file.

    Some entries hold 1 diff or none:

    • When the new version leaves the file unchanged, or the version you ran didn't ship it, the entry holds 1 diff.
    • A binary file or a file over 100 KB gets no diff, and its entry holds a note to recover your copy from version control. The update changes only the working tree, so restore your copy with git checkout HEAD -- FILE_PATH, replacing FILE_PATH with the path in the entry's heading.

  5. When you re-apply your own README.md changes, keep the new version in the Vortex badge. The next update reads the badge to work out which version your project runs.

  6. Reconcile composer.json. The update replaces it with the template's version, which most likely differs from yours, so review the package version changes carefully. If .logs/vortex-update.md has an entry for composer.json, restore your own file from Git, then apply the new version's change from that entry by hand. Keep the raised drevops/vortex-tooling constraint: a release that changes the scripts raises it, and the old constraint keeps the old scripts.

  7. Run ahoy composer update. This command regenerates composer.lock, which the update leaves alone, so the build installs the versions from your reconciled composer.json.

  8. Stage and commit the changes in small chunks, so each one is easier to review and revert.

  9. Rebuild your local environment and check that everything works:

    Test the updated environment
    ahoy build

    When the build asks to remove the containers, build files and database, answer y. The build provisions the site again and ends with the project information, including the site's local URL and a one-time login link.

  10. Push the branch:

    Push the update branch
    git push origin update-vortex

  11. Open a pull request for the branch, and wait for its continuous integration run to pass.

  12. After the run passes, check that the site deployed to your preview or staging environment.
    Test the updated site there thoroughly before you release it to production.

  13. Schedule the production release, and leave enough time for spot checks and a possible rollback.

Confirm that the update is complete:

  • The Vortex badge in README.md shows the version you updated to.
  • Every entry this update added to .logs/vortex-update.md is resolved and deleted.

Best practices​

Follow these practices:

  • Update Vortex monthly, or at least quarterly, to keep your project secure and up to date, and sooner when a release carries security patches.
  • Test each update in development before it reaches production.
  • Update environments in stages: development → staging → production.
  • Keep track of what changed and why.
  • Watch for issues in the days after an update.

Get help​

If you hit a problem during an update:

➡️ See Support

What's next​