@continuous-excellence/ze-great-dashboard-aws 0.3.0 → 0.3.2
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.
- package/README.md +108 -94
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,133 +1,147 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Ze Great Dashboard AWS deployment
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
[](LICENSE)
|
|
3
|
+
`@continuous-excellence/ze-great-dashboard-aws` packages a configured Ze Great Dashboard as an AWS
|
|
4
|
+
Lambda deployment. It includes the compatible immutable client, Lambda runtime, CLI, and
|
|
5
|
+
CloudFormation template.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
It does not create a public endpoint, choose an authentication policy, create a gateway, provide a
|
|
8
|
+
secret value, or own consumer AWS infrastructure. You provide the protected gateway and complete the
|
|
9
|
+
administrator-owned bootstrap process first.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
whatever a team actually walks over to check. It stores nothing, computes no trends, and holds no
|
|
12
|
-
opinion about your process. Every panel is a live read of a system that already knows the answer.
|
|
11
|
+
## Prerequisites
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
You need Node.js 22+, npm, the AWS CLI, `jq`, and one AWS Region for the artifact bucket, Lambda,
|
|
14
|
+
and application stack. You also need a consumer-owned artifact bucket and the bootstrap-created
|
|
15
|
+
restricted roles. Follow the [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
|
|
16
|
+
before this deployment procedure.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
panels work end to end. Azure DevOps remains to be built.
|
|
18
|
+
## Deploy a dashboard
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
Use an exact package version in a deployment project:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
npm install
|
|
24
|
-
npm run dev
|
|
23
|
+
npm install --save-exact @continuous-excellence/ze-great-dashboard-aws@1.2.3
|
|
25
24
|
```
|
|
26
25
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
26
|
+
Create `board.yaml`. This small configuration has one GitHub Actions panel and one HTTP value panel;
|
|
27
|
+
see the [board configuration guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
|
|
28
|
+
for the full schema.
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
sources:
|
|
32
|
+
github:
|
|
33
|
+
type: github-actions
|
|
34
|
+
repo: your-org/your-repo
|
|
35
|
+
branch: main
|
|
36
|
+
token_env: GITHUB_TOKEN
|
|
37
|
+
|
|
38
|
+
boards:
|
|
39
|
+
operations:
|
|
40
|
+
refresh: 60s
|
|
41
|
+
panels:
|
|
42
|
+
- id: build
|
|
43
|
+
type: pipeline-status
|
|
44
|
+
source: github
|
|
45
|
+
pipeline: main.yml
|
|
46
|
+
position: { x: 0, y: 0, w: 8, h: 6 }
|
|
47
|
+
- id: version
|
|
48
|
+
type: http-value
|
|
49
|
+
url: https://status.example.com/version.json
|
|
50
|
+
json_path: $.version
|
|
51
|
+
position: { x: 8, y: 0, w: 4, h: 6 }
|
|
38
52
|
```
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
Before you commit anything:
|
|
54
|
+
Generate the application parameters from the non-secret `dashboard-bootstrap.json` created during
|
|
55
|
+
bootstrap:
|
|
43
56
|
|
|
44
57
|
```sh
|
|
45
|
-
npm
|
|
58
|
+
npm exec -- ze-great-dashboard-aws parameters \
|
|
59
|
+
--bootstrap-config dashboard-bootstrap.json \
|
|
60
|
+
--output aws-dashboard-parameters.json
|
|
46
61
|
```
|
|
47
62
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
`core.hooksPath`, no extra setup.
|
|
51
|
-
|
|
52
|
-
Set `PLAYWRIGHT_DOCKER=1` to run the browser portion through the matching official Playwright
|
|
53
|
-
container. The root test script starts the Compose service, connects the existing test to it, and
|
|
54
|
-
tears it down afterward:
|
|
63
|
+
After the parameter file exists, run the read-only doctor. It checks local tooling, your AWS
|
|
64
|
+
identity, parameters, the artifact bucket and Region, and the matching hosted client:
|
|
55
65
|
|
|
56
66
|
```sh
|
|
57
|
-
|
|
67
|
+
npm exec -- ze-great-dashboard-aws doctor \
|
|
68
|
+
--parameters aws-dashboard-parameters.json \
|
|
69
|
+
--region us-east-1
|
|
58
70
|
```
|
|
59
71
|
|
|
60
|
-
|
|
72
|
+
Package the release. This validates the board and writes `lambda.zip`, `release.json`, and
|
|
73
|
+
`template.yml` to the output directory:
|
|
61
74
|
|
|
62
75
|
```sh
|
|
63
|
-
|
|
64
|
-
|
|
76
|
+
npm exec -- ze-great-dashboard-aws package \
|
|
77
|
+
--board-config board.yaml \
|
|
78
|
+
--output aws-dashboard-release
|
|
65
79
|
```
|
|
66
80
|
|
|
67
|
-
|
|
68
|
-
build involved. This is how you reproduce production behavior, or confirm that a specific published
|
|
69
|
-
version renders.
|
|
70
|
-
|
|
71
|
-
If you want to point it at something served from your own machine instead of the CDN, use the host's
|
|
72
|
-
LAN address, not `host.docker.internal` — on Docker Desktop that name can resolve to IPv6, and Node's
|
|
73
|
-
`fetch` will fail against an IPv4-only local server while `wget` in the same container succeeds. The
|
|
74
|
-
symptom is a refused start naming a URL you can reach perfectly well from the host.
|
|
81
|
+
Upload the generated ZIP to the bucket and key specified by the parameter file and release metadata:
|
|
75
82
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
a versioned CDN path, containing **zero environment values**. The server fetches that version's
|
|
80
|
-
`index.html` at request time, injects a `window.env` block as the first element of `<head>`, and
|
|
81
|
-
serves it uncached.
|
|
83
|
+
```sh
|
|
84
|
+
export AWS_REGION=us-east-1
|
|
85
|
+
export STACK_NAME=my-ze-great-dashboard
|
|
82
86
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
87
|
+
ARTIFACT_BUCKET="$(jq -er \
|
|
88
|
+
'.[] | select(.ParameterKey == "LambdaArtifactBucket") | .ParameterValue' \
|
|
89
|
+
aws-dashboard-parameters.json)"
|
|
90
|
+
ARTIFACT_KEY="$(jq -er '.artifactKey' aws-dashboard-release/release.json)"
|
|
86
91
|
|
|
92
|
+
aws s3 cp aws-dashboard-release/lambda.zip \
|
|
93
|
+
"s3://${ARTIFACT_BUCKET}/${ARTIFACT_KEY}" \
|
|
94
|
+
--region "$AWS_REGION"
|
|
87
95
|
```
|
|
88
|
-
browser ──► server (Lambda) ──fetch index.html──► CDN /dashboard/1.0.7/
|
|
89
|
-
│ (immutable, cached hard)
|
|
90
|
-
└── injects window.env, cache-control: no-store
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
Structurally that means:
|
|
94
96
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
credentials, stores nothing.
|
|
98
|
-
- **`packages/shared`** — the board config schema and signal envelope. The one definition both sides
|
|
99
|
-
agree on, so changing it is a single coordinated change the type checker enforces.
|
|
97
|
+
Deploy the generated CloudFormation template using the restricted execution role captured from the
|
|
98
|
+
core bootstrap stack:
|
|
100
99
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
100
|
+
```sh
|
|
101
|
+
aws cloudformation deploy \
|
|
102
|
+
--stack-name "$STACK_NAME" \
|
|
103
|
+
--template-file aws-dashboard-release/template.yml \
|
|
104
|
+
--role-arn "$CLOUDFORMATION_EXECUTION_ROLE_ARN" \
|
|
105
|
+
--region "$AWS_REGION" \
|
|
106
|
+
--capabilities CAPABILITY_NAMED_IAM \
|
|
107
|
+
--parameter-overrides file://aws-dashboard-parameters.json \
|
|
108
|
+
--no-fail-on-empty-changeset
|
|
109
|
+
```
|
|
105
110
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
111
|
+
The stack outputs `ServerFunctionArn`. Integrate that ARN with your protected API Gateway, ALB, or
|
|
112
|
+
other consumer-owned gateway, then verify the protected `/health` endpoint. The template deliberately
|
|
113
|
+
does not grant public Lambda invoke permission.
|
|
109
114
|
|
|
110
|
-
|
|
111
|
-
and the value lives in the environment. `.env` is gitignored; `.env.example` names every variable and
|
|
112
|
-
holds no values.
|
|
115
|
+
## Operate safely
|
|
113
116
|
|
|
114
|
-
|
|
117
|
+
To upgrade, install a newer exact package version and repeat package, upload, and deploy. A change to
|
|
118
|
+
`board.yaml` follows the same path; it does not require a package change.
|
|
115
119
|
|
|
116
|
-
|
|
120
|
+
Tokens belong in runtime secret handling, never in board YAML, `aws-dashboard-parameters.json`, or
|
|
121
|
+
the generated ZIP. See [runtime secrets](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#runtime-secrets)
|
|
122
|
+
for the supported secret reference and integration boundary.
|
|
117
123
|
|
|
118
|
-
|
|
119
|
-
[Tagger](https://github.com/robertfmurdock/tagger), publishes its versioned client assets, and deploys
|
|
120
|
-
the exact npm tarball to the repository-owned consumer reference. Only then does it publish that
|
|
121
|
-
same tarball and tag the release.
|
|
124
|
+
## Commands and boundaries
|
|
122
125
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
`
|
|
126
|
-
|
|
127
|
-
|
|
126
|
+
| Command | Use |
|
|
127
|
+
| --- | --- |
|
|
128
|
+
| `doctor` | Read-only preflight for an existing parameter file. |
|
|
129
|
+
| `parameters` | Generate or update application CloudFormation parameters. |
|
|
130
|
+
| `package` | Validate board YAML and build a deployable Lambda release. |
|
|
131
|
+
| `bootstrap` | Produce bootstrap templates, parameters, preflight, and guidance; administrators run AWS commands explicitly. |
|
|
132
|
+
| `publish-assets` | Provider-only: publish immutable client assets. Normal consumers use the hosted client. |
|
|
133
|
+
| `deploy` | Provider-only: automation helper for a provider-managed asset and Lambda deployment. |
|
|
128
134
|
|
|
129
|
-
|
|
135
|
+
## Further reading and support boundary
|
|
130
136
|
|
|
131
|
-
|
|
137
|
+
- [Board configuration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
|
|
138
|
+
- [AWS bootstrap](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
|
|
139
|
+
- [Consumer deployment and CI setup](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
|
|
140
|
+
- [GitHub Actions deployment workflow YAML example](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#github-actions)
|
|
141
|
+
- [Runtime secret integration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#runtime-secrets)
|
|
142
|
+
- [Repository source](https://github.com/robertfmurdock/ze-great-dashboard)
|
|
143
|
+
- [Issue tracker](https://github.com/robertfmurdock/ze-great-dashboard/issues)
|
|
144
|
+
- [MIT license](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/LICENSE)
|
|
132
145
|
|
|
133
|
-
|
|
146
|
+
The package owns the Lambda deployment artifact. Gateway design, authentication, secret-value
|
|
147
|
+
provisioning, and consumer AWS account administration remain your responsibility.
|