Deploying Backstage on AWS Lightsail

DISCLAIMER: The deploy command is in alpha and still experimental. Do not use the deploy command for production deployments.

Getting started with Backstage often involves setting up an instance on a cloud provider and sharing it with your team so they can experiment. To make this cloud deployment easier, we've built a deploy command to stand up a proof-of-concept instance on AWS (using Lightsail).

What is AWS Lightsail

tip

AWS offers a free tier for up to three months on $10 USD/month Container service (Micro -1 node). By default we use the nano node, so if you are a new user this approach shouldn't cost you anything. For more information, refer to the pricing documentation.

AWS Lightsail offers a simple way to run containers in the cloud. To learn more about AWS Lightsail, please refer to the official documentation.

Creating user in AWS

• Open the AWS console and navigate to the IAM section
• In the left side menu click on Users and then click on Add users
• Specify a username and then click on Next
• Afterwards you can assign permissions, select Attach policies directly and then click on Create policy. This should take you to a new window in which you can create a new policy based on JSON. Copy over the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ecr:DescribeImageReplicationStatus",
        "ecr:ListTagsForResource",
        "ecr:UploadLayerPart",
        "ecr:BatchGetRepositoryScanningConfiguration",
        "ecr:DeleteRepository",
        "ecr:GetRegistryScanningConfiguration",
        "ecr:CompleteLayerUpload",
        "ecr:TagResource",
        "ecr:DescribeRepositories",
        "ecr:DeleteRepositoryPolicy",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetLifecyclePolicy",
        "ecr:GetRegistryPolicy",
        "ecr:PutLifecyclePolicy",
        "ecr:DescribeImageScanFindings",
        "ecr:GetLifecyclePolicyPreview",
        "ecr:CreateRepository",
        "ecr:DescribeRegistry",
        "ecr:GetDownloadUrlForLayer",
        "ecr:GetAuthorizationToken",
        "ecr:DeleteLifecyclePolicy",
        "ecr:PutImage",
        "ecr:UntagResource",
        "ecr:SetRepositoryPolicy",
        "ecr:BatchGetImage",
        "ecr:InitiateLayerUpload",
        "ecr:GetRepositoryPolicy",
        "lightsail:CreateContainerService",
        "lightsail:GetKeyPair",
        "lightsail:GetContainerServiceDeployments",
        "lightsail:CreateContainerServiceRegistryLogin",
        "lightsail:GetContainerImages",
        "lightsail:UntagResource",
        "lightsail:RegisterContainerImage",
        "lightsail:GetContainerServices",
        "lightsail:GetContainerServicePowers",
        "lightsail:GetKeyPairs",
        "lightsail:CreateContainerServiceDeployment",
        "lightsail:GetContainerServiceMetricData",
        "lightsail:GetContainerAPIMetadata",
        "lightsail:DeleteContainerService",
        "lightsail:GetContainerLog",
        "lightsail:TagResource"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Statement1",
      "Effect": "Allow",
      "Action": [],
      "Resource": []
    }
  ]
}

Then click on Next and give the policy a name and a description of your liking. Afterwards, click on Create policy.

• Navigate back to the user creation window and press on the refresh button and search for the policy you just created. Now, create the user.
• Now you will be redirected to all users, click on the user you just created and click on Security credentials
• Scroll below and click on Create access key
• Choose Command Line Interface (CLI)
• Now export the following values

$ export AWS_ACCESS_KEY_ID=... (first value)
$ export AWS_SECRET_ACCESS_KEY=.... (second secret value)

Configuring the Pulumi CLI

Second, install the Pulumi CLI - backstage-deploy uses it to simplify the management of cloud resources (Pulumi allows us to simply specify the desired "target cloud state", and Pulumi will intelligently create/modify/delete resources to reach that state. Nice!).

Then we need to execute the following commands, to set Pulumi up:

tip

Make sure to store your passphrase somewhere safe as it is used to encrypt/decrypt your Pulumi config.

$ pulumi login --local
$ export PULUMI_CONFIG_PASSPHRASE="<your-secret>"

By using pulumi login --local we are making sure that Pulumi stores our state on the local file disk. The environment variable PULUMI_CONFIG_PASSPHRASE is used by Pulumi to generate a unique key for your stack

Deploying your instance on Lightsail

tip

Make sure that Docker is running on your machine before you start this section.

After you have made your changes to your local instance, it's time to deploy it on Lightsail.

First, we need to configure a new app-config file and update the baseUrl.

$ touch app-config.deployment.yaml

And then update the file with the following yaml:

app:
  baseUrl: ${BACKSTAGE_HOST}

backend:
  baseUrl: ${BACKSTAGE_HOST}

The environment variable BACKSTAGE_HOST will be set to the endpoint that AWS Lightsail creates.

Now we can deploy our instance!

$ npx backstage-deploy aws --stack backstage-poc --create-dockerfile

In the first part of the command, we are specifying that we want to deploy our instance on AWS. With the --stack option, we are providing Pulumi a reference to our container deployment. Furthermore, with the --create-dockerfile option, there will be a Dockerfile and .dockerignore created in the root of the project.

After running the command, Pulumi will start creating the following resources for you in AWS:

• ECR Repository
• Lightsail Container Service
• Lightsail Container Service Deployment
• Policy that allows Lightsail to pull from ECR

If it's the first time building the Docker image, it might take a while for everything to be fully provisioned. After the command is finished running, your Backstage instance should be up and running on AWS Lightsail! 🎉

Cleaning up resources

Cleaning up the resources is also done with the deploy command.

$ npx backstage-deploy aws --stack backstage-poc --destroy

This will delete everything that was originally created by the deploy command.