Skip to main content

Installation

Installing the Orchestrate Platforms and Applications (OPA) on AWS solution will provide you with the complete reference implementation including authentication/authorization, a Backstage platform instance, source code management, and CI/CD pipelines. By following this guide you will:

  • Deploy the AWS infrastructure required to run OPA on AWS
  • Deploy a GitLab source code management instance including provisioning of resources to run CI/CD pipelines
  • Configure authentication/authorization using Okta as the identity provider (Backstage supports several other identity providers)
  • Deploy a sample repository of example software templates to create apps, environments, and resources for AWS

Prerequisites​

Software prerequisites​

The following software is required to perform the installation of the platform solution:

  • Unix-based operating system (Linux, MacOS, or the Windows Subsystem for Linux)
  • node.js - 18.19 or higher
  • yarn - v1.x (Yarn classic)
  • aws-cli
  • aws-cdk
  • jq
  • docker
  • git
  • python Make sure to use Python 3.11, Python 3.12+ has issues due to distutils removal
note

The installation instructions documented here were tested using the following versions:

  • node v18.19
  • aws-cdk v2.95
  • yarn 1.22.21
  • python 3.11

Solution Platform prerequisites​

Prior to installing the OPA solution platform, you will need to ensure that the following items are configured and available:

  • AWS Account ID and region - The solution will be installed into an AWS account and region. You will need the 12-digit account ID and must be able to log into the account with sufficient permissions to provision infrastructure resources.

  • GitLab Community Edition EC2 AMI id - The solution will install a small GitLab instance where application source code will be stored. The AWS Marketplace provides a free, community edition of GitLab used by the solution.

    • You will need to subscribe to the AWS Marketplace offering. Search for "GitLab Community Edition" by GitLab or use a direct link: https://aws.amazon.com/marketplace/pp/prodview-w6ykryurkesjq
    • Once your account is subscribed to the GitLab CE Marketplace offering, save the EC2 AMI for the appropriate region from the "Launch new instance" page as shown in the image below (do not actually launch an instance as this will be done for you during installation).
      Marketplace GitLab EC2 AMI
      Alternatively, you can query for the AMI using the AWS CLI (substitute the appropriate region value for the --region option): 

      aws ec2 describe-images --owners "aws-marketplace" --filters "Name=name,Values=*GitLab CE 16.8.1*" --query 'Images[].[ImageId]' --region <AWS_REGION> --output text

  • GitLab Runner image - The solution will set up an EC2 instance as a GitLab Runner to execute GitLab CI/CD pipelines. The Amazon-provided "Jammy" image will be used for the runner image. Save the EC2 AMI for the appropriate region for this AMI. The following AMI command will return the appropriate image id. Replace the value for "--region" to reflect your target region:


    aws ec2 describe-images --owners "amazon" --filters "Name=name,Values=*ubuntu-jammy-22.04-amd64-server-20230208*" --query 'Images[].[ImageId]' --region <AWS_REGION> --output text

  • Route 53 Hosted Zone - The solution will ensure secure communcations and set up a certificate for your defined domain. Ensure that a public hosted zone is set up in your account. See the AWS documentation for creating a public hosted zone

  • Okta authentication - The solution uses Okta and RoadieHQ Backstage plugins for authentication of users and groups. You will need a client id, client secret, and API key for configuration of the solution. If you wish to use Okta for authentication and do not have an existing account, you can sign up a free Workforce Identity Cloud developer account.

Installation​

  1. Clone the repository and change to the repository location

    git clone https://github.com/awslabs/app-development-for-backstage-io-on-aws.git
    cd app-development-for-backstage-io-on-aws

  2. Configure the solution

    1. Copy the config/sample.env file to config/.env
    2. Edit the config/.env file and provide values for all of the environment variables. The file is commented to explain the purpose of the variables and requires some of the information from the Solution Platform Prerequisites section above.
    info

    The SECRET_GITLAB_CONFIG_PROP_apiToken, OKTA_IDP and OKTA_AUTH_SERVER_ID variables do not need to be provided. This will be automatically configured during installation after the platform is deployed.

  3. Perform the installation

    1. Run make install
      The Makefile target will automatically perform the following actions:

      • Install and configure Backstage

      • Install/update CDK

      • Deploy the solution platform AWS infrastructure

      • Update the configuration with GitLab information

      • Push a sample repository to GitLab

      • Build and deploy the Backstage image to AWS

    • After the installation completes, the application will start up. Open a browser and navigate to the 'OPA on AWS' endpoint using the Route 53 hosted zone name that you configured (e.g. https://${R53_HOSTED_ZONE_NAME}).

    • If any errors occur during installation, please review the install_{datestamp}.log file for details.

    • a new secret manager's secret named opa-admin-gitlab-secrets contains the Gitlab admin's credentials for

Installation FAQs​

I don't use Okta. Can i change the identity provider to another one?

Yes. Backstage supports many identity providers. Once you configure Backstage for your chosen provider, make sure the Backstage catalog is synced with the users and groups from your provider.


I want to use another source control that is not GitLab. How can i do that?

Backstage supports multiple source control providers which can be integrated through the Backstage config. OPA uses GitLab for several usage scenarios which you will need to migrate to another source control provider:

  1. Storing application source code
  2. Storing template source code
  3. Storing pipelines jobs and orchestration
  4. Update the Client API plugin that interacts with GitLab to the new source control provider

I'm using Terraform, can I use this solution with Terraform to provision application resources?

Yes. We provide a Node.js Terraform application software template for demonstration. You may also write your own provider with Terraform.


For more Q & A please see our FAQ Page