ngrok-sdk-serverless

An example of using the ngrok-js NodeJS SDK in an AWS App Runner serverless application.

Prerequisites

1. A fork of this repository made into your own Github account user
2. An AWS account with App Runner enabled

Non-Production Use Case

This method will get an app up and running as quickly as possible, but will not protect the Auth Token to a high enough standard for Production use cases.

1. Navigate to the App Runner service within the AWS console
2. Click Create service
3. Source: Choose Source code repository
   1. Click Add New
      1. Follow the prompts to connect AWS to your forked repository. More information is available here
   2. It should automatically choose the connected repository, otherwise select it
   3. Click Next at the bottom
4. Build settings: Choose Configure all settings here
   1. Runtime: Nodejs 16
   2. Build command: npm install
   3. Start command: npm start
   4. Click Next at the bottom
5. Service name: ngrok-serverless
   1. Environment variables: Add environment variable:
      1. Plain text (not for Prod use): name: NGROK_AUTHTOKEN, value: paste in your ngrok Auth Token
   2. Networking: Incoming: Choose Private endpoint
      1. Click Create new endpoint
         1. Select VPC, Subnets: select all availability zones
         2. Click Create
      2. Choose the newly created VPC Endpoint
   3. Click Next at the bottom
6. Click Create & Deploy at the bottom
7. After the service is deployed, you can find the ngrok ingress URL by clicking on the link in the Application logs section of the service details page. You may need to refresh using the circular arrow button

Production Use Case

For production use the Auth Token must be pulled from an encrypted store. This can be done through AWS Secrets Manager or SSM Parameter Store, the latter is free so the example will use SSM Parameter Store. See the AWS documentation for more information on how to do this.

Add secret

1. Create secrets in the AWS Systems Manager Parameter Store
   1. Navigate to the Parameter Store service within the AWS console
   2. Click Create parameter
   3. Name: /ngrok-serverless/ngrok-authtoken
   4. Type: SecureString
   5. Value: paste in your ngrok auth token
   6. Click Create parameter
2. In the forked Github repository: Edit the apprunner.yaml file to change the NGROK_AUTHTOKEN environment variable to use the AWS Secrets Manager secret
   1. Uncomment and fill in the region, account_id, and parameter_name of the secret for this line: value-from: "arn:aws:ssm:<region>:<aws_account_id>:parameter/<parameter_name>
   2. Commit and push the changes to your forked repository
3. Create IAM role for App Runner to access the secret
   1. Navigate to the IAM service within the AWS console
   2. Click Roles
   3. Click Create role
      1. Select Custom trust policy
      2. Paste in the Example IAM Role Trust Policy from below, replacing the existing JSON text
      3. Click Next
   4. Click Create policy. In the new tab:
      1. Click JSON
         1. Paste in the Example IAM Policy from below, replacing the region, account_id, and parameter_name with the values from the secret
         2. Click Next
      2. Policy name: ngrok-serverless-policy
         1. Click Create policy
   5. Back in the Create role tab:
      1. Click the two-arrows refresh button to update the list of policies
      2. Search for ngrok
      3. Check the box next to the ngrok-serverless-policy that was created in the previous step
      4. Click Next
   6. Role name: ngrok-serverless-role
      1. Click Create role

Example IAM Role Trust Policy

Example IAM Role Trust Policy from the AWS documentation:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "tasks.apprunner.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Example IAM Policy

Example IAM Policy from the AWS documentation:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters"
      ],
      "Resource": [
        "arn:aws:ssm:<region>:<aws_account_id>:parameter/<parameter_name>"
      ]
    }
  ]
}

Add App Runner service

1. Navigate to the App Runner service within the AWS console
2. Click Create service
3. Source: Choose Source code repository
   1. Click Add New
      1. Follow the prompts to connect AWS to your forked repository. More information is available here
   2. It should automatically choose the connect repository, otherwise select it
   3. Click Next at the bottom
4. Build settings: Choose Use a configuration file
   1. Click Next at the bottom
5. Service name: ngrok-serverless
   1. Security: Instance role
      1. Select the IAM role created in the previous step, e.g. ngrok-serverless-role
   2. Networking: Incoming: Choose Private endpoint
      1. Click Create new endpoint
         1. Select VPC, Subnets: select all availability zones
         2. Click Create
      2. Choose the newly created VPC Endpoint
   3. Click Next at the bottom
6. Click Create & Deploy at the bottom
7. After the service is deployed, you can find the ngrok ingress URL within your ngrok dashboard as it will show up as a connected agent

Next Steps

See the App Runner documentation for more information on how to use the service.

See the ngrok-nodejs documentation for more information on how to use the ngrok NodeJS SDK library.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ngrok-nodejs by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.