Configuration settings

Stage name

A stage name is used to allow multiple Service Workbench deployments from the same account. It represents the name of the configuration files. For limitations in Amazon Simple Storage Service (Amazon S3) deployment buckets, the stage name must not be longer than five characters. Buckets are the fundamental containers in Amazon S3 for data storage. You can select your own stage name. If you are planning to deploy the solution only once, a common convention, is to use your own login. In the following sections of the guide, customized stage name is represented as <stage>.

Separately deployable components

The Service Workbench code is divided into multiple (currently seven) separately deployable components (SDCs): backend, UI, post-deployment, pre-deployment, edge-lambda, infrastructure, machine-images, and prepare-aster-acc. Each SDC has a directory in the location, main/solution. You can run the script either from the root directory or also deploy each SDC separately using individual scripts. For more information, see serverless framework and projects.

Prepare the main configuration file

You can make a copy of the sample global AWS Config file, name it for your stage, and modify it. The current default values for the main configuration are stored in the default file in the directory, main/config/settings/.defaults.yml. If the stage-named settings file is not available, the values are read from this default file.

To create a custom (stage-named) settings file, in the directory, main/config/settings, copy example.yml to <stage>.yml and edit this new file. Default values are read from .defaults.yml unless the values are overridden in this file. Following table describes the default values:

Configuration	Value
awsRegion	us-east-1
awsProfile	No default; set this to your current AWS profile unless using a default or instance profile.
solutionName	sw
envName	Same as stage name
envType	prod
enableExternalResearchers	false

Custom Identity Provider

The Service Workbench built-in IdP is Cognito User Pool, if you don't want to use Cognito User Pool as IdP or the deployment region does not support Cognito User Pool, such as Beijing, Ningxia and Hongkong. You can use external OIDC IdPs, such as Keycloak, Authing and Okta to integrate with Service Workbench.

To use OIDC IdP, you need install or apply OIDC IdP at first, refer OIDC Providers Settings, and then add below configurations in <stage>.yml file:

defaultIdpType: oidc
oidcIssuer: xxx
oidcClientId: xxx
rootUserEmail: xxx
rootUserFirstName: xxx
rootUserLastName: xxx

Custom domain names

To use a custom domain name, enter the domain name and the ARN for the manually created TLS certificate.

domainName: host.domain.toplevel
certificateArn: <ARN>

• Note: The current implementation assumes that DNS is handled elsewhere. A future improvement will automatically handle creation of the cert and Route 53 entries.
• Note: This is an optional step during Service Workbench installation. For Beijing/Ningxia regions, domainName configuration is mandatory. please refer China Regions Prerequisites to create ICP licensed domain.
• Note: If DNS resolution is not managed in current aws account Route 53, please set customDomainInR53 config as false.

Accessing Web Portal through Applicaiton Load Balancer

Service Workbench allows customer to deploy it without domain through Amazon Application Load Balancer(ALB) exposing web portal. To use ALB to expose web portal, you need to add below configurations into <stage>.yml file:

enableAlb: true
albSubnetIdList: 'subnet-xxx,subnet-xxx'
albVpcId: 'vpc-xxx'
albPort: 8000

• enableAlb: Set the value of this configuration as true to enable ALB exposing web portal feature. The default value is false if you don't add enableAlb into <stage>.yml file
• albSubnetIdList: This configuration works when enableAlb is true. The ALB will be created in these subnets.
• albVpcId: This configuration works when enableAlb is true. The ALB will be created in specified VPC.
• albPort: The listening port of the ALB. The default value is 8000.

If you enable ALB feature, after you deployed the solution, you will get the Alb URL in terminal output. You also can get Alb URL info through scripts/get-info.sh script.

Disable Lambda@Edge

Service Workbench allows customer to disable lambda@edge to reduce lambda function calling. To disable lambda@edge, please add below configuration into <stage>.yml file:

enableLambdaEdge: false

• enableLambdaEdge: Set the value of this configuration as false to disable lambda@edge. The default value is true if you don't add enableLambdaEdge into <stage>.yml file

lambda@edge is responsible for adding some security header in http response. Please refer to code snippet to learn about what security headers are included.

Namespace

The names of many deployed resources include a namespace string such as mystage-va-sw. This string is made by concatenating the following:

• Environment name
• Region short name (for example: va for US-East-1, or for US-West-2, defined in .defaults.yml)
• Solution name

Other configurations for Beijing/Ningxia regions

Please set below configurations in <stage>.yml file if you deploy Service Workbench in Beijing/Ningxia region.

awsPartition: aws-cn
awsSuffix: amazonaws.com.cn

Prepare SDC configuration files

Each SDC has a config/settings directory, where you can place customized settings. Settings files are named after the stage name <mystagename.yml>. Some of the SDC settings directories contain an example.yml file that may be copied and renamed as a settings file for that SDC. Otherwise, a default file .defaults.yml in that directory is read and used regardless of the stage name.

Note: This is an optional step during Service Workbench installation.

Accessing the Service Workbench source code

Download the latest source code by using this link, copy Source code (zip) link address, and run the following command: wget <URL>, then run unzip to decompress code package

Note: Setting the configuration is required. If you are deploying an installation, you can use the default configuration.

Supported regions

The following regions support all the AWS services and features needed to run Service Workbench:

• US East (Ohio)
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Mumbai)
• Asia Pacific (Seoul)
• Asia Pacific (Singapore)
• Asia Pacific (Sydney)
• Asia Pacific (Tokyo)
• Canada (Central)
• Europe (Frankfurt)
• Europe (Ireland)
• Europe (London)
• Europe (Paris)
• Europe (Stockholm)
• South America (São Paulo)
• China (Beijing) Region Operated by Sinnet
• China (Ningxia) Region operated by NWCD
• Asia Pacific (Hong Kong)