Skip to main content

Installation

These steps take you from an empty directory to a deployed site. Follow them in order: every step uses only what the previous steps produced.

Installing Vortex into a new project​

1. Choose the names​

The installer asks for a Site name, a Site machine name, an Organization name, an Organization machine name, a Custom modules prefix, and a Theme name. Choose these deliberately before running it: the machine names end up in directory names, module names, and code across the whole project, so they are typed constantly and are costly to change later. Keep them short, easy to write, and clearly distinguishable from each other.

  • Custom modules prefix - built from the first letters of the site name: the first two letters for a single-word name (Falcon becomes fa), or the first letter of each word for a multi-word name (Star Wars becomes sw). Custom modules then read as sw_base, sw_search, and so on.
  • Theme name - the whole site name, shortened as much as possible and without underscores where possible (Star Wars becomes starwars, Falcon becomes falcon). This keeps the theme name and the module prefix from colliding while both stay short enough to type often.

2. Install Vortex​

Create a new directory for your project, navigate into it, and run the installer:

Install using interactive prompts
curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php

Installing with an AI agent

The installer has built-in support for AI agents. Run it with --agent-help to get instructions for a non-interactive, programmatic installation:

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

The command above installs the current stable Vortex release (the 1.x line today). To target a specific major version explicitly, use its dedicated path:

  • https://www.vortextemplate.com/v1/install - the current 1.x line.
  • https://www.vortextemplate.com/v2/install - the 2.x line, currently in development.

Once installed, ahoy update-vortex keeps your project on its major version - it never jumps across a major release. See Updating Vortex.

3. Commit the initial project structure​

git add .
git commit -m "Initial commit"

4. Create a GitHub repository and push​

Create a new repository on GitHub and push the initial commit to it.

5. Create an SSH key for deployments​

The automation uses SSH for 2 operations: fetching the database from the hosting provider and deploying code to it. Generate a key pair for them:

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

The -m PEM -t rsa format is accepted by every supported hosting and continuous integration provider.

You can also generate 2 separate key pairs - one with read access for database fetches and one with write access for deployments - so that each can be revoked independently. The steps below note where each key is used.

The public key (the .pub file) is registered with your hosting provider in the next step; the private key stays with you until the continuous integration setup and never goes anywhere else.

6. Set up hosting​

Choose your hosting provider. For how the site behaves on each platform, see the Hosting section.

  1. Add the public key created in step 5 to your Acquia account, so the automation can fetch databases and push code artifacts. When using separate keys, add both public keys.
  2. Add VORTEX_ACQUIA_APP_NAME with your Acquia application name (machine name) to your .env file, commit and push.
  3. Create an Acquia Cloud API key and secret for the account that runs the automation, and keep both values at hand: the continuous integration setup in the next step stores them as secrets.

Acquia supplies a per-environment hash_salt through its platform settings file, which Vortex includes automatically (see Acquia settings file), so you do not need to set DRUPAL_HASH_SALT.

7. Set up continuous integration​

The workflow is identical for both providers - choose one. For workflow structure, jobs, and caching, see the Continuous integration section.

  1. Vortex ships the workflow at .github/workflows/build-test-deploy.yml and GitHub Actions is on by default. Open the Actions tab to confirm it is detected.
  2. Add the private key created in step 5 under Settings → Secrets and variables → Actions as 2 secrets: VORTEX_DB_SSH_KEY for database fetches and VORTEX_DEPLOY_SSH_KEY for deployments. When using separate keys, add each private key to its own secret.
  3. Add the hosting credentials from step 6 in the same screen: for Acquia, the API key and secret as VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET; for Lagoon, the private key again as LAGOON_SSH_KEY.

8. Run your first build​

Push to a branch or open a pull request. Your continuous integration provider builds the codebase, runs the tests, and deploys according to your configuration.

Installing Vortex into an existing project​

The installer cannot predict the state of your project, so initialize Vortex into a clean checkout and merge your existing project into it.

warning

Back up your project before proceeding.

1. Choose the names​

The installer asks for a Site name, a Site machine name, an Organization name, an Organization machine name, a Custom modules prefix, and a Theme name. Choose these deliberately before running it: the machine names end up in directory names, module names, and code across the whole project, so they are typed constantly and are costly to change later. Keep them short, easy to write, and clearly distinguishable from each other.

  • Custom modules prefix - built from the first letters of the site name: the first two letters for a single-word name (Falcon becomes fa), or the first letter of each word for a multi-word name (Star Wars becomes sw). Custom modules then read as sw_base, sw_search, and so on.
  • Theme name - the whole site name, shortened as much as possible and without underscores where possible (Star Wars becomes starwars, Falcon becomes falcon). This keeps the theme name and the module prefix from colliding while both stay short enough to type often.

2. Copy your project aside​

Copy all files (including hidden files) from your existing project into a temporary directory.

3. Clean the working copy​

In your existing project, create a new branch and remove all files 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

5. Commit the installed structure​

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

6. Merge your project back​

Copy your files back from the temporary directory, overriding the installed ones. Review the diff and selectively keep changes: merge composer.json by hand, preserving all of Vortex's entries, regenerate composer.lock with a reviewed composer update, and check the result with composer validate.

7. Commit and push​

Commit the result to the branch and push it to the remote repository.

8. Create an SSH key for deployments​

The automation uses SSH for 2 operations: fetching the database from the hosting provider and deploying code to it. Generate a key pair for them:

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

The -m PEM -t rsa format is accepted by every supported hosting and continuous integration provider.

You can also generate 2 separate key pairs - one with read access for database fetches and one with write access for deployments - so that each can be revoked independently. The steps below note where each key is used.

The public key (the .pub file) is registered with your hosting provider in the next step; the private key stays with you until the continuous integration setup and never goes anywhere else.

9. Set up hosting​

Choose your hosting provider. For how the site behaves on each platform, see the Hosting section.

  1. Add the public key created in step 8 to your Acquia account, so the automation can fetch databases and push code artifacts. When using separate keys, add both public keys.
  2. Add VORTEX_ACQUIA_APP_NAME with your Acquia application name (machine name) to your .env file, commit and push.
  3. Create an Acquia Cloud API key and secret for the account that runs the automation, and keep both values at hand: the continuous integration setup in the next step stores them as secrets.

Acquia supplies a per-environment hash_salt through its platform settings file, which Vortex includes automatically (see Acquia settings file), so you do not need to set DRUPAL_HASH_SALT.

10. Set up continuous integration​

The workflow is identical for both providers - choose one. For workflow structure, jobs, and caching, see the Continuous integration section.

  1. Vortex ships the workflow at .github/workflows/build-test-deploy.yml and GitHub Actions is on by default. Open the Actions tab to confirm it is detected.
  2. Add the private key created in step 8 under Settings → Secrets and variables → Actions as 2 secrets: VORTEX_DB_SSH_KEY for database fetches and VORTEX_DEPLOY_SSH_KEY for deployments. When using separate keys, add each private key to its own secret.
  3. Add the hosting credentials from step 9 in the same screen: for Acquia, the API key and secret as VORTEX_ACQUIA_KEY and VORTEX_ACQUIA_SECRET; for Lagoon, the private key again as LAGOON_SSH_KEY.

11. Run your first build​

Push to a branch or open a pull request. Your continuous integration provider builds the codebase, runs the tests, and deploys according to your configuration.

Updating Vortex​

Head to Updating Vortex for detailed instructions on how to update your project to the latest version of Vortex.