@continuous-excellence/ze-great-dashboard-aws 0.31.0 → 0.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +81 -78
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,74 +1,56 @@
1
1
  # Ze Great Dashboard on AWS
2
2
 
3
- `@continuous-excellence/ze-great-dashboard-aws` packages a board for a private AWS Lambda or ECS
4
- deployment. It includes the Lambda runtime, deployment CLI, and CloudFormation templates; browser
5
- assets are published separately as `@continuous-excellence/ze-great-dashboard-client`.
6
-
7
- Deployment mode is persisted in `dashboard-bootstrap.json` and generated application parameters
8
- as `ComputeMode`. Existing files without that field mean `lambda`. Choose `--mode ecs` during
9
- bootstrap initialization; routine packaging and diagnostics then select the matching template.
10
- An explicit mode fails if it disagrees with persisted configuration, so changing mode requires
11
- regenerating the reviewed bootstrap and parameter artifacts.
12
-
13
- `dashboard-bootstrap.json` is checked-in desired state, not a capture of AWS. If an intentionally
14
- upgraded package changes a bootstrap template contract or revision, run `bootstrap upgrade
15
- --config dashboard-bootstrap.json`, review and commit only that metadata change, then have the
16
- consumer's approved deployment automation preview and execute CloudFormation UPDATE change sets.
17
- Package upgrades that do not change bootstrap template identity do not require a manifest update or
18
- bootstrap redeploy. Captures and generated parameter files are disposable deployment artifacts;
19
- the package owns template contents and the manifest records the intended package/template identity.
20
- No credentials belong in the manifest.
21
-
22
- Consumer ECS deployments use the long-lived service template and provide their own subnets and
23
- security groups.
24
-
25
- This deployment path is intended for teams that already operate AWS and have a protected gateway
26
- such as API Gateway or an ALB. It deliberately does not create a public endpoint, choose an
27
- authentication policy, or manage secret values.
28
-
29
- If you are evaluating the dashboard, start with the repository's
30
- [local setup](https://github.com/robertfmurdock/ze-great-dashboard#run-it-locally). You do not need
31
- AWS to try it.
32
-
33
- ## What you need
3
+ `@continuous-excellence/ze-great-dashboard-aws` validates and packages a board for a private AWS Lambda
4
+ or ECS deployment. It includes the server runtime, deployment CLI, and CloudFormation
5
+ templates. The matching immutable browser client is published separately as
6
+ `@continuous-excellence/ze-great-dashboard-client` and is selected automatically unless you provide
7
+ another exact asset URL.
8
+
9
+ This package is for teams that already operate AWS and can provide a protected entry path:
10
+
11
+ - Lambda requires a consumer-owned API Gateway, ALB, or equivalent gateway with private invocation
12
+ permission.
13
+ - ECS requires consumer-owned subnets, security groups, and protected load balancing or routing for
14
+ the long-lived Fargate service.
15
+
16
+ In both modes, a consumer-owned gateway or load balancer defines the public entry and authentication
17
+ boundary.
18
+
19
+ The templates create no public endpoint, choose no authentication policy, and manage no secret
20
+ values. To evaluate the dashboard without AWS, start with the
21
+ [local setup](https://github.com/robertfmurdock/ze-great-dashboard#try-it).
22
+
23
+ ## Prerequisites
34
24
 
35
25
  - Node.js 22 or newer, npm, the AWS CLI, and `jq`.
36
- - An AWS administrator for the one-time bootstrap.
37
- - A pre-existing central GitHub OIDC provider and a protected GitHub Environment if GitHub Actions
38
- will deploy the dashboard.
39
- - A consumer-owned gateway that can privately invoke Lambda and enforce your access policy.
40
-
41
- The included deployment works out of the box with public GitHub repositories and HTTP endpoints
42
- that do not require credentials. For private GitHub sources, `SecretReference` is the ARN of one
43
- consumer-owned Secrets Manager JSON map or Parameter Store `SecureString` (for example,
44
- `{"GITHUB_TOKEN":"github_pat_…"}`). The runtime resolves configured `token_env` names only at
45
- Lambda cold start and never exposes token values to the browser, API responses, logs,
46
- CloudFormation parameters, or Lambda environment. The two added AWS SDK clients provide
47
- IAM-authenticated `GetSecretValue` and decrypted `GetParameter` support in the bundled Lambda, at
48
- the cost of their bundled code and one cold-start request when private sources are configured.
49
-
50
- ## Deployment map
51
-
52
- 1. An administrator creates the artifact bucket and restricted deployment roles using the
53
- [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md).
54
- 2. The application owner writes `board.yaml`, packages the Lambda, and deploys its private
55
- CloudFormation stack using the
56
- [deployment guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md).
57
- 3. The consumer connects the returned `ServerFunctionArn` to its protected gateway.
58
- 4. GitHub Actions can repeat the package-and-deploy step after the administrator configures the two
59
- reviewed role ARNs.
60
-
61
- ## The normal application workflow
62
-
63
- Pin an exact package version in the repository that owns the deployment:
26
+ - An AWS administrator for one-time bootstrap.
27
+ - A pre-existing account-level GitHub OIDC provider and protected GitHub Environment when GitHub
28
+ Actions will deploy the dashboard.
29
+ - Consumer-owned networking, gateway or load balancing, authentication, and runtime health checks.
30
+
31
+ ## Choose and bootstrap a compute mode
32
+
33
+ Lambda is the compatibility default. Select ECS with `--mode ecs` when running `bootstrap init`.
34
+ The choice is stored in `dashboard-bootstrap.json` and generated application parameters as
35
+ `ComputeMode`; older files without the field mean Lambda.
36
+
37
+ An explicit mode that conflicts with persisted configuration fails. Changing between Lambda and ECS
38
+ requires regenerated, administrator-reviewed bootstrap and application parameters—it is not a
39
+ routine package option.
40
+
41
+ Follow the [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md),
42
+ then the [Lambda deployment guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md).
43
+
44
+ ## Package a deployment
45
+
46
+ Pin the reviewed package version in the repository that owns the deployment:
64
47
 
65
48
  ```sh
66
49
  npm install --save-exact @continuous-excellence/ze-great-dashboard-aws
67
50
  ```
68
51
 
69
- Append `@version` when installing a previously reviewed release rather than the current one.
70
-
71
- After bootstrap is complete, the recurring workflow is only:
52
+ Append `@version` when installing a previously reviewed release rather than the current one. After
53
+ bootstrap, generate and diagnose application parameters, then package the board:
72
54
 
73
55
  ```sh
74
56
  npm exec -- ze-great-dashboard-aws parameters \
@@ -85,29 +67,50 @@ npm exec -- ze-great-dashboard-aws package \
85
67
  --output aws-dashboard-release
86
68
  ```
87
69
 
88
- `package` writes the complete release-specific `parameters.json` and machine-readable
89
- `deployment.json` alongside the ZIP and template. The deployment guide covers executing the emitted
90
- S3 upload and CloudFormation commands, gateway handoff, and CI example.
91
- Changing `board.yaml` or upgrading the pinned package uses this same path.
70
+ For ECS, the persisted parameters select the ECS template and `package` also requires an immutable,
71
+ digest-pinned image through `--image`. The generated `deployment.json` contains structured upload
72
+ and CloudFormation command arguments for the approved deployment process to invoke.
92
73
 
93
- ## Package boundaries
74
+ `package` writes release-specific `parameters.json`, `deployment.json`, and `template.yml`, plus
75
+ `lambda.zip` for Lambda. Changing `board.yaml` or the pinned package version uses this same path.
76
+ Run the read-only `bootstrap check` before every deployment.
94
77
 
95
- | The package owns | You own |
96
- | --- | --- |
97
- | Board validation and Lambda packaging | Board content and source access |
98
- | Server runtime and CloudFormation templates | The immutable browser asset host and authentication |
99
- | Private application CloudFormation template | AWS account administration |
100
- | Restricted bootstrap templates | Secret values and the credential-map ARN |
101
- | Read-only preflight and consistency checks | Reviewing and executing AWS changes |
78
+ ## Private source credentials
102
79
 
103
- Bootstrap commands never execute mutating AWS operations. They produce plans, parameters, and
104
- commands for an administrator to review and run explicitly. `bootstrap check` is the named
105
- read-only live diagnostic used before routine deployments.
80
+ Public GitHub repositories and unauthenticated HTTP sources work without credentials. For private
81
+ sources, set `SecretReference` to the ARN of one consumer-owned Secrets Manager JSON value or
82
+ Parameter Store `SecureString`, for example:
83
+
84
+ ```json
85
+ {"GITHUB_TOKEN":"github_pat_…"}
86
+ ```
87
+
88
+ The board references `GITHUB_TOKEN` through `token_env`; the credential value never belongs in the
89
+ board, bootstrap manifest, CloudFormation parameters, runtime environment variables, logs, API
90
+ responses, or browser. The runtime reads only the exact secret or parameter authorized by the
91
+ application role, resolves configured `token_env` names only at Lambda cold start, and fails closed
92
+ when a key is absent.
93
+
94
+ ## Ownership boundaries
95
+
96
+ | Package responsibility | Consumer responsibility |
97
+ | --- | --- |
98
+ | Board validation and release packaging | Board content and source permissions |
99
+ | Server runtime and application templates | AWS account and network administration |
100
+ | Restricted bootstrap templates | Reviewing and executing AWS changes |
101
+ | Default immutable client asset selection | Approval of alternate asset hosts |
102
+ | Read-only preflight, doctor, and consistency checks | Gateway, authentication, and health checks |
103
+ | Exact secret-resource integration | Secret values, rotation, and credential-map ARN |
104
+
105
+ Bootstrap commands do not perform mutating AWS operations. They emit plans, parameters, captures,
106
+ and command arguments for an administrator to review and invoke. `bootstrap check` is the read-only
107
+ live diagnostic used before routine deployments; when it fails, use the
108
+ [bootstrap upgrade runbook](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap-upgrade.md).
106
109
 
107
110
  ## References
108
111
 
109
112
  - [Board configuration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
110
113
  - [Administrator bootstrap](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
111
- - [Application deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
114
+ - [Lambda deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
112
115
  - [GitHub Actions deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-github-actions.md)
113
116
  - [Issue tracker](https://github.com/robertfmurdock/ze-great-dashboard/issues)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@continuous-excellence/ze-great-dashboard-aws",
3
- "version": "0.31.0",
3
+ "version": "0.31.1",
4
4
  "type": "module",
5
5
  "description": "AWS server runtime and CloudFormation deployment tooling for Ze Great Dashboard.",
6
6
  "keywords": [