@continuous-excellence/ze-great-dashboard-aws 0.1.21 → 0.1.23
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 +130 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# ze-great-dashboard
|
|
2
|
+
|
|
3
|
+
[](https://github.com/robertfmurdock/ze-great-dashboard/actions/workflows/main.yml)
|
|
4
|
+
[](https://socket.dev/npm/package/@continuous-excellence/ze-great-dashboard-aws)
|
|
5
|
+
[](https://www.npmjs.com/package/@continuous-excellence/ze-great-dashboard-aws)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
A team-visible trust dashboard: **a lens on your engineering state, not a ledger of it.**
|
|
9
|
+
|
|
10
|
+
It shows whether the things your team relies on are currently working — builds, deploys, versions,
|
|
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.
|
|
13
|
+
|
|
14
|
+
Design doc: `ze-great-idea-pit/tool-ideas/trust-dashboard.md`. How this repo came to be shaped the
|
|
15
|
+
way it is, including the quirks that look like bugs: `docs/initialization-log.md`.
|
|
16
|
+
|
|
17
|
+
**Status: first Stage 2 slice.** GitHub Actions `pipeline-status` panels work end to end. Azure
|
|
18
|
+
DevOps and `http-value` adapters remain to be built.
|
|
19
|
+
|
|
20
|
+
## Quickstart
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npm install
|
|
24
|
+
npm run dev
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Then open <http://localhost:3000>.
|
|
28
|
+
|
|
29
|
+
That runs the Vite dev server on 5173 and the app server on 3000, with the server rendering the
|
|
30
|
+
entrypoint from Vite. Edit a component and the page updates — through the real server rendering path,
|
|
31
|
+
not a bypass of it. This is the loop for the visual work.
|
|
32
|
+
|
|
33
|
+
To run a different single-board YAML file, only its path is needed; the server selects its sole
|
|
34
|
+
board automatically:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
BOARD_CONFIG_URL="$PWD/boards/ze-great-team.yaml" npm run dev
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Set `BOARD` as well only when the selected YAML contains multiple boards.
|
|
41
|
+
|
|
42
|
+
Before you commit anything:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
npm run check
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Lint, typecheck, and tests, in about a second and a half. The pre-commit hook runs it too, so a
|
|
49
|
+
broken change can't be committed by accident — the hooks arrive with `npm install` via
|
|
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:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
PLAYWRIGHT_DOCKER=1 npm run check
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### The other mode: the deployed shape
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
cp .env.example .env # set ASSET_PATH to a published version
|
|
64
|
+
docker compose up
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
One container, the server only, pointed at a client version already published to the CDN. No client
|
|
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.
|
|
75
|
+
|
|
76
|
+
## How it works
|
|
77
|
+
|
|
78
|
+
The client is an [Immutable Web Application](https://immutablewebapps.org): built once, published to
|
|
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.
|
|
82
|
+
|
|
83
|
+
The consequence worth caring about: **changing which client version is live is one environment
|
|
84
|
+
variable on the server.** No rebuild, no redeploy of the client, and rollback is the same move in
|
|
85
|
+
reverse.
|
|
86
|
+
|
|
87
|
+
```
|
|
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
|
+
|
|
95
|
+
- **`packages/client`** — the board renderer. React + Vite. Holds no configuration.
|
|
96
|
+
- **`packages/server`** — renders the entrypoint; from Stage 2, proxies signal data. Holds the
|
|
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.
|
|
100
|
+
|
|
101
|
+
`packages/server/test/immutable-web-app.test.ts` proves the whole mechanism against two fixture
|
|
102
|
+
client versions with different hashed filenames, over real HTTP, with no AWS and no credentials.
|
|
103
|
+
|
|
104
|
+
## Configuration
|
|
105
|
+
|
|
106
|
+
Boards are YAML — see `boards/example.yaml` for the small public demo and
|
|
107
|
+
`boards/ze-great-team.yaml` for the realistic radiator. Panels name a signal type and a source; the
|
|
108
|
+
schema is in `packages/shared/src/board-config.ts`.
|
|
109
|
+
|
|
110
|
+
**Credentials never appear in board config.** A source names an environment variable (`token_env:`)
|
|
111
|
+
and the value lives in the environment. `.env` is gitignored; `.env.example` names every variable and
|
|
112
|
+
holds no values.
|
|
113
|
+
|
|
114
|
+
Server environment variables are documented in `.env.example`. The one that matters is `ASSET_PATH`.
|
|
115
|
+
|
|
116
|
+
## Deploying
|
|
117
|
+
|
|
118
|
+
Push to `main`. CI checks, versions with [Tagger](https://github.com/robertfmurdock/tagger), publishes
|
|
119
|
+
the client to S3, and points the Lambda at the new version.
|
|
120
|
+
|
|
121
|
+
Infrastructure is a CloudFormation stack under `infra/`. On `main`, CI deploys the stack before it
|
|
122
|
+
publishes assets and updates the Lambda. Other branches receive no AWS credentials. CloudFormation
|
|
123
|
+
keeps the infrastructure state in AWS; `infra/README.md` documents the one-time GitHub OIDC role
|
|
124
|
+
bootstrap.
|
|
125
|
+
|
|
126
|
+
For a consumer-managed deployment with the published AWS package, see [`docs/aws-setup.md`](docs/aws-setup.md).
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT
|