Configuring external CI for Front End Hosting - Advanced applications

This guide describes how to integrate external continuous integration (CI) with Front End Hosting - Advanced applications. These platform-agnostic instructions adapt to any CI system.

Prerequisites

Before you configure your CI pipeline, ensure that the following requirements are met:

• Install Node.js version 22 or later in the CI environment.
• Install the npm package manager in the CI environment.
• Configure git in the CI environment.
• Set up an SSH key and SVN URL for the Acquia SVN repository in the CI environment.
• Configure required environment variables and secrets in the CI platform.
• Create a file named acquia_config.yaml in the branch root directory.

Required environment variables

Configure these required secrets in your CI platform:

CI pipeline configuration

1. In the root directory of the deployment branch, add an acquia_config.yaml file with the following content:

   copy

   enable-prebuilt-artifact: true

   If acquia_config.yaml is missing or this setting is unspecified, the default is false.

2. Configure the CI/CD pipeline to use Ubuntu or an equivalent Linux distribution. Use a Node.js version supported by Acquia. To learn more about Acquia supported Node.js versions, visit Which Node.js versions are supported by the Front End Hosting - Advanced offering?
   Execute all build processes in a Linux amd64 environment for compatibility.
   Example Node.js installation:

   copy

   # Install Node.js
   # This step varies by CI/CD platform
   # Example for generic Linux environment:
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt-get install -y nodejs

3. Check out the source code of the branch from your repository.

4. Install all required Node.js dependencies:

   copy

   npm install

5. Build your application:

   copy

   npm run build

6. Ensure that acquia_config.yaml and acquia-autoscaling.js are included with all build artifacts. Prepare a clean build directory that contains only necessary deployment files:

   copy

   # Remove any existing build output directory
   rm -rf build-output
   
   # Create new build output directory
   mkdir build-output
   
   # Copy required files and directories, acquia_config.yaml, node_modules and acquia-autoscaling.js
   # Add any framework specific files/folders required for deployment here. The following example demonstrates the configuration for the Next.js framework..
   cp -R _static public package.json next.config.js node_modules acquia_config.yaml acquia-autoscaling.js build-output/
   
   # Note: Add any additional files your application requires for deployment

7. Configure git inside the build output directory:

   copy

   cd build-output
   
   # Initialize Git repository
   git init
   
   # Configure Git user (replace with your details)
   git config user.name "your-username"
   git config user.email "[email protected]"
   
   # Add remote repository
   git remote add target <acquia-svn-repo-url-here>

8. Set up SSH for secure deployment:

   copy

   # Create SSH directory
   mkdir -p ~/.ssh
   
   # Add SSH private key (using your CI/CD platform's secret management)
   echo "$DEPLOY_SSH_KEY" > ~/.ssh/id_rsa
   chmod 600 ~/.ssh/id_rsa
   
   # Add host to known hosts
   ssh-keyscan -H <acquia-svn-host-here> >> ~/.ssh/known_hosts

9. Commit build artifacts and push to the deployment repository:

   copy

   cd build-output
   
   # Create and checkout deployment branch
   git checkout -b $DEPLOY_BRANCH
   
   # Stage all files
   git add .
   
   # Commit changes
   git commit -m "Build output from CI/CD pipeline"
   
   # Force push to deployment branch
   git push target $DEPLOY_BRANCH -f

   For a tag based deployment, use the following:

Configuring external CD for Front End Hosting - Advanced applications

This guide describes how to integrate external continuous deployment (CD) with Front End Hosting - Advanced applications. These platform-agnostic instructions adapt to any CD system.

Prerequisites

Before you begin to set up the CD pipeline, ensure that the following items are available:

• Bash shell in the deployment environment
• curl command-line utility configured
• jq command-line JSON processor available
• Required environment variables and secrets set up in the CD platform
• deploy.sh script created in the branch root directory

Required environment variables

Configure these required secrets in your CI platform:

CD pipeline configuration

1. Obtain the Cloud API Client ID, Cloud API Client Secret, environment ID, and the branch name for deployment. These are required to call the deploy.sh script.

   Set all these values as environment secrets in your CD platform.

   • Generate Cloud API credentials as described on the Cloud Platform API v2 authentication page.

   • The environment ID is visible in the URL when an environment is open in Cloud UI.

     
   • The branch name is the branch you choose for deployment on the environment.

2. Add a deploy.sh script to the project root.

   The script authenticates against accounts.acquia.com and obtains a bearer token. Then the script calls the Cloud API to switch code to the specified branch or tag.

   copy

   #!/bin/bash
   # Usage: ./deploy.sh --environment-id <ENVIRONMENT_ID> --branch <DEPLOY_BRANCH> --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET>
   # OR
   # Usage: ./deploy.sh --environment-id=<ENVIRONMENT_ID> --branch=<DEPLOY_BRANCH> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
   set -e
   
   # Initialize variables
   environmentId=""
   branch=""
   CLIENT_ID=""
   CLIENT_SECRET=""
   
   # Function to display usage
   usage() {
       echo "Usage: $0 --environment-id <ENVIRONMENT_ID> --branch <DEPLOY_BRANCH> --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET>"
       echo "   or: $0 --environment-id=<ENVIRONMENT_ID> --branch=<DEPLOY_BRANCH> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>"
       echo ""
       echo "Options:"
       echo "  --environment-id  Environment ID for deployment"
       echo "  --branch          Git branch to deploy"
       echo "  --client-id       OAuth client ID"
       echo "  --client-secret   OAuth client secret"
       echo "  -h, --help        Show this help message"
       echo ""
       echo "Note: You can use either --flag value or --flag=value format"
       exit 1
   }
   
   # Parse command line arguments
   while [[ $# -gt 0 ]]; do
       case $1 in
           --environment-id=*)
               environmentId="${1#*=}"
               shift
               ;;
           --environment-id)
               environmentId="$2"
               shift 2
               ;;
           --branch=*)
               branch="${1#*=}"
               shift
               ;;
           --branch)
               branch="$2"
               shift 2
               ;;
           --client-id=*)
               CLIENT_ID="${1#*=}"
               shift
               ;;
           --client-id)
               CLIENT_ID="$2"
               shift 2
               ;;
           --client-secret=*)
               CLIENT_SECRET="${1#*=}"
               shift
               ;;
           --client-secret)
               CLIENT_SECRET="$2"
               shift 2
               ;;
           -h|--help)
               usage
               ;;
           *)
               echo "Unknown option: $1"
               usage
               ;;
       esac
   done
   
   # Check for missing parameters
   if [[ -z "$environmentId" || -z "$branch" || -z "$CLIENT_ID" || -z "$CLIENT_SECRET" ]]; then
       echo "Error: All parameters are required."
       echo ""
       usage
   fi
   
   AUTH_SERVER_URL="https://accounts.acquia.com/api/auth/oauth/token"
   CODE_DEPLOYMENT_URL="https://cloud.acquia.com/api/environments/${environmentId}/code/actions/switch"
   
   # Obtain access token
   response=$(curl --silent -L --request POST \
     --url "${AUTH_SERVER_URL}" \
     --header "content-type: application/x-www-form-urlencoded" \
     --data grant_type=client_credentials \
     --data client_id="${CLIENT_ID}" \
     --data-urlencode client_secret="${CLIENT_SECRET}")
   
   # Check if there was an error in the response
   if [[ "$response" == *"error"* ]]; then
     echo "Error in obtaining token:"
     echo "$response"
     exit 1
   fi
   
   # Extract the access token from the JSON response
   access_token=$(echo "$response" | jq -r .access_token)
   
   echo "Access token obtained."
   echo "Deployment URL: $CODE_DEPLOYMENT_URL"
   
   # Trigger code deployment
   response=$(curl --silent -X POST "${CODE_DEPLOYMENT_URL}" \
     -H "Authorization: Bearer $access_token" \
     -H "Content-Type: application/json" \
     -H "Accept: application/hal+json" \
     -d "{
       \"branch\": \"$branch\"
     }")
   
   echo "Deployment response:"
   echo "$response"

Configuring external CI/CD