Installation

These steps take you from an empty directory to a deployed site. The interactive installer scaffolds your codebase; the remaining steps connect it to your hosting platform and continuous integration provider. Follow them in order.

Installing Vortex into a new project

1. 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

2. Commit the initial project structure

git add .
git commit -m "Initial commit"

3. Create a GitHub repository and push

Create a new repository on GitHub and push the initial commit to it. The next two steps connect this repository to your hosting and CI providers.

4. Set up hosting

Choose your hosting provider and add its configuration. For background and routine operations, see the Hosting section.

Acquia

Add to your .env file:

Variable	Description
VORTEX_ACQUIA_APP_NAME	Your Acquia application name (machine name)
DRUPAL_ACQUIA_SETTINGS_FILE	Override the path to Acquia's settings .inc file (optional)
DRUPAL_TMP_PATH	Override the temporary file path (optional)
DRUPAL_TMP_PATH_IS_SHARED	Use Acquia's shared GFS mount for temporary files (optional)

Add as secrets in your CI provider (in step 5):

Variable	Description
VORTEX_ACQUIA_KEY	Your Acquia Cloud API key
VORTEX_ACQUIA_SECRET	Your Acquia Cloud API secret

Hash salt: Acquia supplies a per-environment hash_salt through its platform settings file, which Vortex includes automatically (see Acquia settings file).

warning

You normally do not need to set DRUPAL_HASH_SALT on Acquia - the platform supplies one per environment, and a conflicting value would be overridden.

Drush aliases (optional): to run Drush against remote environments, download your aliases from the Acquia Cloud UI (see Using Drush aliases).

Lagoon

Add to your .env file:

Variable	Description
LAGOON_PROJECT	Your Lagoon project name
VORTEX_DOWNLOAD_DB_LAGOON_SSH_HOST	Lagoon SSH host (default: ssh.lagoon.amazeeio.cloud)
VORTEX_DOWNLOAD_DB_LAGOON_SSH_PORT	Lagoon SSH port (default: 32222)

Add as a secret in your CI provider (in step 5):

Variable	Description
LAGOON_SSH_KEY	SSH private key for Lagoon authentication

Hash salt: Lagoon does not supply one, so set a unique DRUPAL_HASH_SALT for every environment (dev, stage, production) as a Lagoon environment variable.

warning

Set a unique, long, random DRUPAL_HASH_SALT for every Lagoon environment. Without it, the salt is derived from the database host and changes when the host changes, silently invalidating outstanding one-time login and password-reset links.

5. Set up continuous integration

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

GitHub Actions

Enable the workflow. GitHub Actions is on by default; Vortex ships the workflow at .github/workflows/build-test-deploy.yml. Open the Actions tab to confirm it is detected.

Add SSH keys. Generate a key pair, add the public key to your hosting provider, and add the private key(s) as secrets under Settings → Secrets and variables → Actions:

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

• VORTEX_DB_SSH_KEY - key with read access, for database downloads.
• VORTEX_DEPLOY_SSH_KEY - key with write access, for deployment (may be the same key).

Add the hosting secrets from step 4 in the same Settings → Secrets and variables → Actions screen.

Pin host keys (optional). Strict host-key checking is disabled by default. To enable it, add the verified host keys as a VORTEX_SSH_KNOWN_HOSTS repository variable and map it into the workflow env block.

CircleCI

Enable the project. Log in to CircleCI and add your repository; it detects the .circleci/ config and starts building on push.

Add SSH keys. Generate a key pair, add the public key to your hosting provider, and add the private key(s) under Project Settings → SSH Keys (copy each generated fingerprint):

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

Set the fingerprints in .circleci/config.yml: db_ssh_fingerprint (database download) and deploy_ssh_fingerprint (deployment).

Add the hosting variables from step 4 under Project Settings → Environment Variables.

Pin host keys (optional). Add the verified host keys as a VORTEX_SSH_KNOWN_HOSTS environment variable (join multiple entries with \n).

Schedule trigger (optional). If you use the self-hosted Renovate workflow, add an update-dependencies scheduled trigger under Project Settings → Triggers (config source update-dependencies.yml, branch develop).

6. Run your first build

Push to a branch or open a pull request. Your CI 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 new directory and merge your existing project into it.

warning

Back up your project before proceeding.

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

2. In your existing project, create a new branch and remove all files except the .git directory.

3. Run the installer (step 1) to produce a clean Vortex installation, then commit it.

4. 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) and regenerate composer.lock with composer install.

5. Commit the result to the new branch and push to remote.

Then complete step 4 through step 6 to connect hosting and CI.

Updating Vortex

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