Skip to content

Commit 363985a

Browse files
coderbyheartcoderbyheart
committed
docs: restore README
1 parent 9ee22f9 commit 363985a

File tree

1 file changed

+50
-126
lines changed

1 file changed

+50
-126
lines changed

‎README.md‎

Lines changed: 50 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,171 +1,95 @@
1-
# nRF Asset Tracker Web Application for AWS
1+
# Public Parameter Registry for AWS
22

3-
[![GitHub Actions](https://github.com/NordicSemiconductor/asset-tracker-cloud-app-aws-js/workflows/Test%20and%20Release/badge.svg)](https://github.com/NordicSemiconductor/asset-tracker-cloud-app-aws-js/actions)
3+
[![GitHub Actions](https://github.com/hello-nrfcloud/public-parameter-registry-aws-js/workflows/Test%20and%20Release/badge.svg)](https://github.com/hello-nrfcloud/public-parameter-registry-aws-js/actions/workflows/test-and-release.yaml)
44
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
55
[![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com)
6-
[![Mergify Status](https://img.shields.io/endpoint.svg?url=https://api.mergify.com/v1/badges/NordicSemiconductor/asset-tracker-cloud-app-aws-js)](https://mergify.io)
76
[![@commitlint/config-conventional](https://img.shields.io/badge/%40commitlint-config--conventional-brightgreen)](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional)
87
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier/)
98
[![ESLint: TypeScript](https://img.shields.io/badge/ESLint-TypeScript-blue.svg)](https://github.com/typescript-eslint/typescript-eslint)
10-
[![React](https://github.com/aleen42/badges/raw/master/src/react.svg)](https://reactjs.org/)
11-
[![Bootstrap 5](https://img.shields.io/badge/Bootstrap-5-ffffff?labelColor=7952b3)](https://getbootstrap.com/docs/5.0/)
12-
[![CSS modules](https://img.shields.io/badge/CSS-modules-yellow)](https://github.com/css-modules/css-modules)
13-
[![Vite](https://github.com/aleen42/badges/raw/master/src/vitejs.svg)](https://vitejs.dev/)
149

15-
The nRF Asset Tracker Web Application for AWS is a reference single-page
16-
application (SPA) developed with [React](https://reactjs.org/) in
10+
Public Parameter Registry for developed using
11+
[AWS CDK](https://aws.amazon.com/cdk) in
1712
[TypeScript](https://www.typescriptlang.org/).
1813

19-
The UI components are themed using
20-
[Bootstrap 5](https://getbootstrap.com/docs/5.0/) and
21-
[CSS modules](https://github.com/css-modules/css-modules). All complex UI logic
22-
is extracted using [React hooks](https://reactjs.org/docs/hooks-custom.html) to
23-
allow re-use when changing the UI framework.
14+
This project provides a JSON file in a public S3 bucket, that contains all SSM
15+
Parameters under a path that starts with the name of this stack.
2416

25-
[Vite](https://vitejs.dev/) is used as the frontend toolchain.
17+
This is useful to publish for example resource endpoints without relying on AWS,
18+
or configuration settings for web applications without having to redeploy the
19+
application.
2620

27-
> :information_source:
28-
> [Read the complete nRF Asset Tracker documentation](https://nordicsemiconductor.github.io/asset-tracker-cloud-docs/).
21+
It is used in our projects to provide a way to share outputs from CloudFormation
22+
stacks without needed to depend on them directly. This also allows to have a web
23+
application, which might be hosted on a CDN and therefore only exists in on
24+
region, to consume stack outputs from backend stacks in multiple regions.
2925

30-
## Set up
26+
## Installation in your AWS account
3127

32-
npm ci
28+
### Setup
3329

34-
## Configuration
30+
Provide your AWS credentials, for example using the `.envrc` (see
31+
[the example](.envrc.example)).
3532

36-
In the
37-
[nRF Asset Tracker for AWS](https://github.com/NordicSemiconductor/asset-tracker-cloud-aws-js)
38-
folder, run `node cli web-app-config` and store the output in a local `.envrc`
39-
file. Then run `direnv allow` to allow it.
33+
Install the dependencies:
4034

4135
```bash
42-
# .envrc
43-
export PUBLIC_CELL_GEO_LOCATION_CACHE_TABLE_NAME=...
44-
export PUBLIC_CLOUDFRONT_DISTRIBUTION_ID=...
45-
export PUBLIC_FOTA_BUCKET_NAME=...
46-
export PUBLIC_GEOLOCATION_API_URL=...
47-
export PUBLIC_HISTORICALDATA_TABLE_INFO=...
48-
export PUBLIC_IDENTITY_POOL_ID=...
49-
export PUBLIC_NETWORK_SURVEY_GEOLOCATION_API_URL=...
50-
export PUBLIC_NETWORKSURVEY_STORAGE_TABLE_NAME=...
51-
export PUBLIC_USER_IOT_POLICY_NAME=...
52-
export PUBLIC_USER_POOL_ID=...
53-
export PUBLIC_USER_POOL_CLIENT_ID=...
54-
export PUBLIC_WEB_APP_BUCKET_NAME=...
55-
export PUBLIC_WEB_APP_DOMAIN_NAME=...
56-
export PUBLIC_SENTRY_DSN=...
57-
export PUBLIC_REGION=...
58-
export PUBLIC_MQTT_ENDPOINT=...
36+
npm ci
5937
```
6038

61-
## Running
62-
63-
npm start
64-
65-
## End-to-end tests using Playwright
66-
67-
The frontend provides [end-to-end tests](./e2e-tests) using
68-
[Playwright](https://playwright.dev/).
69-
70-
### Configure AWS credentials
71-
72-
The end-to-end tests run against an instance of the
73-
[nRF Asset Tracker for AWS](https://github.com/NordicSemiconductor/asset-tracker-cloud-aws-js).
74-
75-
Either, use the credentials you created, when setting up the solution, or enable
76-
the Web App CI feature and use the dedicated credentials created for this task.
77-
The latter option is the recommended approach since it limits the permission
78-
scope to only the needed ones. They can also be used to
79-
[run the end-to-end tests on GitHub Actions](#running-end-to-end-tests-using-github-actions).
80-
81-
Add these environment variables to your `.envrc`. Then run `direnv allow` to
82-
allow it.
39+
### Deploy
8340

8441
```bash
85-
# .envrc
86-
export AWS_REGION=...
87-
export AWS_ACCESS_KEY_ID=...
88-
export AWS_SECRET_ACCESS_KEY=...
89-
export WEBAPP_STACK_NAME=...
42+
# Optionally, configure the stack name to use a suitable name for your project:
43+
export STACK_NAME="my-project-registry"
44+
npx cdk deploy
9045
```
9146

92-
### Running the tests
93-
94-
You can then run the tests using
95-
96-
npm run test:e2e
97-
98-
### Running individual tests
47+
### Setting parameters
9948

100-
npx playwright test authenticated/map/locationHistory/gnss.spec.ts
49+
Use SSM:
10150

102-
### Playwright Inspector
103-
104-
For developing tests it is helpful to run the
105-
[Playwright Inspector](https://playwright.dev/docs/inspector).
106-
107-
You can enabled the inspector during the tests by running
108-
109-
PWDEBUG=1 npm run test:e2e
110-
111-
### Running end-to-end tests using GitHub Actions
51+
```bash
52+
aws ssm put-parameter --name /${STACK_NAME:-public-parameter-registry}/public/some-parameter --type String --value "Some Value"
53+
```
11254

113-
[This workflow](./.github/workflows/test-and-release.yaml) runs the end-to-end
114-
tests for every commit. For this to work a running instance of
115-
[nRF Asset Tracker for AWS](https://github.com/NordicSemiconductor/asset-tracker-cloud-aws-js)
116-
is needed. The tests will be run against this instance. Typically it will be the
117-
production instance, to ensure that the web application works with the current
118-
production setup.
55+
For parameters to be published, they must be below the path
56+
`/<stack name>/public/`.
11957

120-
In order for the test runner to interact with the instance for retrieving the
121-
app configuration and for providing test data you need to configure AWS
122-
credentials as
123-
[GitHub environment secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-an-environment).
58+
## CD with GitHub Actions
12459

125-
Set these secrets:
60+
Create a GitHub environment `production`.
12661

127-
- `AWS_REGION`
128-
- `AWS_ACCESS_KEY_ID`
129-
- `AWS_SECRET_ACCESS_KEY`
130-
- `WEBAPP_STACK_NAME`
62+
<!-- FIXME: add CLI comment -->
13163

132-
If you have enabled the web application CI of the nRF Asset Tracker for AWS
133-
(`node cli configure context stack web-app-ci 1`) you can acquire them using the
134-
nRF Asset Tracker for AWS CLI:
64+
Store the role name from the output as a GitHub Action secret:
13565

13666
```bash
137-
node cli web-app-ci -s
67+
CD_ROLE_ARN=`aws cloudformation describe-stacks --stack-name ${STACK_NAME:-public-parameter-registry} | jq -r '.Stacks[0].Outputs[] | select(.OutputKey == "cdRoleArn") | .OutputValue' | sed -E 's/\/$//g'`
68+
gh variable set AWS_REGION --env production --body "${AWS_REGION}"
69+
gh secret set AWS_ROLE --env production --body "${CD_ROLE_ARN}"
70+
# If you've used a custom stack name
71+
gh variable set STACK_NAME --env production --body "${STACK_NAME}"
13872
```
13973

140-
You can set the secrets through the GitHub UI (make sure to create the
141-
`production`
142-
[environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
143-
in your repository first).
74+
## CI with GitHub Actions
14475

145-
Alternatively you can use the [GitHub CLI](https://cli.github.com/) using the
146-
environment settings from above:
76+
Configure the AWS credentials for an account used for CI, then run
14777

14878
```bash
149-
gh secret set AWS_REGION --env production --body "${AWS_REGION}"
150-
gh secret set AWS_ACCESS_KEY_ID --env production --body "${AWS_ACCESS_KEY_ID}"
151-
gh secret set AWS_SECRET_ACCESS_KEY --env production --body "${AWS_SECRET_ACCESS_KEY}"
152-
gh secret set WEBAPP_STACK_NAME --env production --body "${WEBAPP_STACK_NAME}"
79+
npx cdk --app 'npx tsx cdk/ci.ts' deploy
15380
```
15481

155-
## Sentry
156-
157-
Optionally, Sentry can be enabled for the web application. Export the
158-
`PUBLIC_SENTRY_DSN` environment variable.
82+
This creates a role with Administrator privileges in that account, and allows
83+
the GitHub repository of this repo to assume it.
15984

160-
To enable this in the continuous deployment pipeline of nRF Asset Tracker,
161-
configure the DSN using the CLI:
85+
Create a GitHub environment `ci`.
16286

163-
```bash
164-
./cli.sh configure thirdParty sentry sentryDsn https://4f901247818d46099a3f15b6ada9390e@o4504255385174016.ingest.sentry.io/4504684789170176
165-
```
87+
<!-- FIXME: add CLI comment -->
16688

167-
When the next deployment is triggered, the DSN becomes available via
89+
Store the role name from the output as a GitHub Action secret:
16890

16991
```bash
170-
./cli.sh web-app-config
92+
CI_ROLE_ARN=`aws cloudformation describe-stacks --stack-name ${STACK_NAME:-public-parameter-registry}-ci | jq -r '.Stacks[0].Outputs[] | select(.OutputKey == "roleArn") | .OutputValue' | sed -E 's/\/$//g'`
93+
gh variable set AWS_REGION --env ci --body "${AWS_REGION}"
94+
gh secret set AWS_ROLE --env ci --body "${CI_ROLE_ARN}"
17195
```

0 commit comments

Comments
 (0)