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 the following requirements are met:

• Install Node.js version 20 or higher 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

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

• 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, click here.
  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

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

• Install all required Node.js dependencies:

  copy

  npm install

• Build your application:

  copy

  npm run build

• Ensure 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

• 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>

• 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

• 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

• After deployment, verify that the Cloud Platform UI lists and completes a commit-based deployment task for your environment. Confirm that the intended branch has been successfully deployed to your environment.

  

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 setting up the CD pipeline, ensure 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

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

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

  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