Installation

This page is for the developer or tech lead who sets up a Drupal project on Vortex. It takes you from an empty directory to a project that builds, tests and deploys in continuous integration. Follow the steps in order, because each step uses what the earlier steps produced.

To add Vortex to a site you already have, follow the existing project steps. To update a project that already runs Vortex, see Updating Vortex.

Before you begin

Make sure you have the following:

• PHP 8.3 or later
• curl, git, tar and composer on your PATH
• A GitHub account for the project repository
• A user account on Acquia or Lagoon, if you host there
• A CircleCI account, if you use CircleCI

To build the site on your machine, you also need:

• Docker with Docker Compose
• Ahoy
• A running Pygmy

The installer checks for git, tar and composer when it starts, and stops with a Missing required command error if 1 of them is missing.

Install Vortex into a new project

1. Choose the names

Settle the project's names before you run the installer. The machine names end up in directory names, module names and code across the whole project. You'll type them constantly, and they're costly to change later. The installer asks for these names:

• Site name
• Site machine name
• Organization name
• Organization machine name
• Custom modules prefix
• Custom theme machine name

It asks for the custom theme machine name only when you keep the default Custom (next prompt) answer at the Theme prompt. The other answers, Olivero, Claro and Stark, are core themes that need no name.

Keep the machine names short, quick to type and distinct from each other. These patterns work for the 2 names you'll type most:

• Custom modules prefix - the first letters of the site name. Use the first 2 letters of a single-word name (Falcon becomes fa), or the first letter of each word of a multi-word name (Star Wars becomes sw). Your custom modules then read as sw_base and sw_search.
• Custom theme machine name - the whole site name, as short as possible and without underscores where possible (Star Wars becomes starwars, Falcon becomes falcon). The theme name and the module prefix then stay distinct, and both stay short enough to type often.

The installer suggests different values. For a 1-word site machine name, it suggests the first 4 letters as the prefix. For the theme, it suggests the site machine name itself, such as star_wars. Change either suggestion at the prompt to match your pattern.

2. Install Vortex

In a new, empty directory for your project, run the installer:

Install using interactive prompts

curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php

Complete the installation in the installer:

1. Press any key to start the prompts.
2. Answer each prompt, using the names from step 1. To go back to the previous prompt, press Ctrl+U.
3. Review the Installation summary that follows the last prompt.
4. Confirm Proceed with installing Vortex?. The installer copies the files into the directory and shows Finished installing Vortex.
5. Answer Run the site build now?:
   • Yes builds the site on your machine with the tools from Before you begin. The build takes about 5 to 10 minutes and shows Site is ready when it succeeds.
   • No skips the build. Run ahoy build later.

To have an AI coding agent install Vortex, run the installer with --agent-help. It prints the instructions an agent follows for a non-interactive installation:

curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php --agent-help

Major versions

The /install path serves the installer for the major line this site documents at /docs. Each installer installs the latest release of its own line, or its development branch when the line has no release yet. To install a specific line, download the installer from that line's path:

• https://www.vortextemplate.com/v1/install for the 1.x line
• https://www.vortextemplate.com/v2/install for the 2.x line

After installation, ahoy update-vortex keeps your project on its major line. See Updating Vortex.

3. Commit the initial project structure

The installer initializes a Git repository in the directory. Commit the files it created:

git add .
git commit -m "Initial commit"

4. Create a GitHub repository and push

To put the project on GitHub:

1. Create an empty repository on GitHub and leave out the README, license and .gitignore files, so the repository has no commits that conflict with yours.
2. Push the initial commit with the commands GitHub shows for an existing repository. GitHub then lists your files on the repository's page.

5. Create an SSH key for deployments

For the artifact and lagoon deployment types, your continuous integration pipeline deploys code over SSH. On Lagoon, it fetches the database over SSH too. On Acquia, it downloads database backups through the Acquia Cloud API with the API key from the next step.

If you answered Other or None at the Hosting provider prompt, only these answers need the keys:

• The Code artifact deployment type
• The Lagoon webhook deployment type
• The Lagoon environment database source

If you chose none of them, skip to the next step.

Generate a key pair for the automation:

ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject@example.com" -f ~/.ssh/deployer_myproject -N ""

The command writes the private key to the path after -f and the public key to the same path with .pub added, neither with a passphrase. Replace the example project name in the comment and the path with your own. Every supported hosting and continuous integration provider accepts the -m PEM -t rsa format.

You can also generate 2 separate key pairs: 1 with read access for database fetches and 1 with write access for deployments. You can then revoke each key on its own. Acquia uses only the deployment key, because it fetches the database through the API. The following steps say where each key goes.

You register the public key (the .pub file) with your hosting provider in the next step. Keep the private key on your machine until the continuous integration setup, and copy it nowhere else.

6. Set up hosting

For each answer you selected at the Deployment types prompt, the installer adds its type to VORTEX_DEPLOY_TYPES in .env. The following table maps each answer to its type, its setup page and its line in the deploy log:

Answer	Type	Setup page	Deploy log line
Code artifact	artifact	Artifact deployment	Finished artifact deployment.
Lagoon webhook	lagoon	Lagoon deployment	Finished Lagoon deployment.
Custom webhook	webhook	Webhook deployment	Finished webhook deployment.

If you answered Other or None at the Hosting provider prompt, you have no platform to set up. Set your type's CI variables in your CI provider: repository variables in GitHub Actions, or project environment variables in CircleCI. Artifact deployment and Webhook deployment list the variables.

The Hosting section explains how the site behaves on each platform. For Acquia or Lagoon, pick the tab for your hosting provider:

Acquia

To set up Acquia:

1. Add the public key from step 5 to your Acquia account, so the automation can push code artifacts to your application's Git repository. With separate keys, add the deployment key.
2. Check VORTEX_ACQUIA_APP_NAME in your .env file. The installer fills it with your Hosting project name answer, which defaults to the site machine name.
3. If your Acquia application name (machine name) differs, correct the value in .env, then commit and push the change.
4. Under Account > API tokens in the Acquia Cloud UI, create an Acquia Cloud API token for the account that runs the automation. The token gives you an API key and secret, and the pipeline downloads database backups with them. Keep both values and your application's Git repository URL for the next step.

On Acquia, leave DRUPAL_HASH_SALT unset. The platform's settings file supplies a per-environment hash_salt, and Vortex includes that file automatically (see Acquia settings file).

Lagoon

To set up Lagoon:

1. Add the public key from step 5 to your Lagoon user, so the automation can fetch databases and trigger deployments. With separate keys, add both public keys.
2. Check LAGOON_PROJECT in your .env file. The installer fills it with your Hosting project name answer, which defaults to the site machine name.
3. If your Lagoon project name differs, correct it in .env and in drush/sites/lagoon.site.yml, then commit and push the change.
4. Set a unique, long, random DRUPAL_HASH_SALT variable on every Lagoon environment (dev, stage, production), because Lagoon doesn't supply a salt. Without the variable, Vortex derives it from the database host. When the host changes, the salt changes too, so every outstanding one-time login and password-reset link stops working without an error.

7. Set up continuous integration

If you answered None at the Continuous Integration provider prompt, the project has no pipeline, so skip this step and step 8.

Both providers run the same workflow. The Continuous integration section covers its structure, jobs and caching. Pick the tab for the provider you chose in the installer:

GitHub Actions

To set up GitHub Actions:

1. Open your repository's Actions tab. It lists the Database, Build, Test and Deploy workflow from .github/workflows/build-test-deploy.yml, which GitHub Actions runs without further setup.
2. If you created a key in step 5, add the private key under Settings > Secrets and variables > Actions as the VORTEX_DEPLOY_SSH_PRIVATE_KEY secret, for deployments. With separate keys, use the deployment key.
3. On Lagoon, add the private key as the VORTEX_FETCH_DB_SSH_PRIVATE_KEY secret too, for database fetches. With separate keys, use the read-only key. Acquia fetches the database through the Acquia Cloud API, so it needs no such secret.
4. On Acquia, add the API key and secret from step 6 as the VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET repository secrets.
5. On Acquia, add these 2 variables under Settings > Secrets and variables > Actions > Variables:
   • VORTEX_DEPLOY_ARTIFACT_GIT_REMOTE: your application's Git repository URL
   • VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAIL: the email address for the deployment commits

On Lagoon, the pipeline fetches and deploys with the 2 SSH key secrets.

CircleCI

To set up CircleCI:

1. Log in to CircleCI.
2. Add your repository as a project. CircleCI detects the .circleci/ config and builds every push from then on.
3. If you created keys in step 5, add the private key under Project Settings > SSH Keys. With separate keys, add both private keys. Otherwise, remove the add_ssh_keys steps from the database, deploy and deploy-tags jobs in .circleci/config.yml, then skip to step 6. CircleCI requires each listed fingerprint to match a key in the project settings.
4. Copy the fingerprint that CircleCI generates for each key you added.
5. Set the fingerprints in the aliases list at the top of .circleci/config.yml: db_ssh_fingerprint for database fetches and deploy_ssh_fingerprint for deployments. With a single key, both take the same fingerprint. On Acquia, the database job loads the db_ssh_fingerprint key but doesn't use it, so set db_ssh_fingerprint to the deployment key's fingerprint too.
6. Commit and push the change to .circleci/config.yml.
7. On Acquia, add the API key and secret from step 6 under Project Settings > Environment Variables as VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET.
8. On Acquia, add these 2 variables on the same screen:
   • VORTEX_DEPLOY_ARTIFACT_GIT_REMOTE: your application's Git repository URL
   • VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAIL: the email address for the deployment commits

On Lagoon, the pipeline fetches and deploys with the SSH keys you added.

8. Run your first build

Push to a branch your pipeline builds, such as main or develop, or open a pull request against 1 of them. Your continuous integration provider builds the codebase, runs the tests and deploys according to your configuration. If a required value is missing, the job fails with a Missing required value for ... message that names the variable.

Confirm that the first build passed:

• In GitHub Actions, every job of the Database, Build, Test and Deploy run for your push passes.
• In CircleCI, every job of the commit workflow for your push passes.
• On either provider, the log of the deploy job's Deploy step shows 1 line for each type you chose at the Deployment types prompt. The table in step 6 maps each answer to its line: Finished artifact deployment., Finished Lagoon deployment. or Finished webhook deployment..

Install Vortex into an existing project

The installer can't predict what state your project is in, so you install Vortex into a clean working copy, then merge your existing project back into it.

warning

In step 3, you delete every file in the working copy except the .git directory. Back up your project before you start.

1. Choose the names

Choose the names as in step 1 of the new project steps.

2. Copy your project aside

Copy all files from your existing project, hidden files included, into a temporary directory outside the project.

3. Clean the working copy

To prepare an empty branch in your existing project:

1. Create a new branch.
2. Remove all files, hidden files included, except the .git directory.

4. Install Vortex

Run the installer in the cleaned working copy:

Install using interactive prompts

curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php

Answer the prompts as in step 2 of the new project steps. At Run the site build now?, answer No, because your own code isn't back in place yet.

5. Commit the installed structure

Commit the files the installer created:

git add .
git commit -m "Initial Vortex commit"

6. Merge your project back

To bring your own code back on top of the installed structure:

1. Copy your files back from the temporary directory over the installed ones.
2. Review the diff and keep changes selectively.
3. Merge composer.json by hand so every Vortex entry survives, including the drevops/vortex-tooling requirement that provides the scripts.
4. Run composer update to regenerate composer.lock, then review its changes.
5. Run composer validate to check the result. It reports ./composer.json is valid when the file passes.

7. Commit and push

To save the merged project to your repository:

1. Commit the result to the branch.
2. Push the branch to the remote repository.

8. Set up deployments and continuous integration

Follow the rest of the new project steps in order:

1. Create an SSH key for deployments.
2. Set up hosting.
3. Set up continuous integration.
4. Run your first build, and confirm that it passed.

What's next

• Updating Vortex - bringing in each new Vortex release
• Development - the day-to-day commands for working on the project
• Continuous integration - the pipeline's jobs, caching and maintenance tasks
• Deployment - the deployment types and notifications
• Hosting - how the site behaves on Acquia and Lagoon