docs: Refresh self install - #1106
Conversation
|
@copilot resolve the merge conflicts in this pull request |
Co-authored-by: christopher-hakkaart <76951771+christopher-hakkaart@users.noreply.github.com>
pditommaso
left a comment
pditommaso
left a comment
There was a problem hiding this comment.
Review: self-install docs refresh
The restructure is the right shape — two-path index, assemblable manifests, a shared verification page, settings pushed out to reference.md. But the pages don't run yet. Reviewed at 1e4e10d; every item below re-checked by hand against src/main.
Won't work
Two that stop a deployment cold:
aws-build.md:377enables scan withoutwave.scan.reports.path.ObjectStorageOperationsFactory.create0throws on a null path, andApplication.groovy:43starts Micronaut witheagerInitSingletons(true)— so Wave won't boot.reference.md:378already marks the key required.aws-build.md:272createswave-build-pvcin namespacewave, but line 362 runs build jobs inwave-build. PVCs are namespace-scoped, so every build/scan/mirror pod stays Pending.
And a regression: the merge commit reverted six keys in reference.md from kebab-case back to camelCase, undoing #1096 (master had all six right). They still bind from YAML because Micronaut hyphenates every key it loads, but WAVE_BLOBCACHE_STORAGE_ACCESSKEY no longer resolves — and lines 563/581 still say blob-cache.*, so the section contradicts itself.
Four more that fail silently:
DOCKER_USER/DOCKER_PATinwave.env(docker-compose.md:110) do nothing. Nothing insrc/mainreads those names — they work only via theconfig.ymlthe image ships (build.gradle:184), which this guide tells you to mount over.- The
MICRONAUT_ENVIRONMENTSstrings inconfigure-wave.md:78,130,326re-addlite, andWaveLitegates outJobManager,JobServiceImpl, both job queues and cleanup via@Requires(missingBeans = WaveLite). - The
endpoints.healthguard master shipped (health.jdbc/health.disk-spaceoff) was dropped, while/healthis now the liveness probe in both guides. A brief Postgres blip restarts every replica. WAVE_JVM_OPTSwas dropped from a 4 GiB pod;src/main/jib/launch.shdefaults to-Xmx850m.
Also: the registry snippet at kubernetes-lite.md:146 is a second top-level wave: block (Wave loads one YAML document); that page never says kubectl apply; its ingress has no ingressClassName or annotations so /service-info can't pass; the <s3-bucket> the ConfigMap depends on is never created; noarch is missing from the node selector so mirror pods skip the build node group; the production checklist uses the legacy wave.allowAnonymous alias instead of wave.capabilities.anonymous-access; and how-wave-works.md:126 still links ./configuration.md.
Simplify
Length is concentrated in three blocks: the seven-registry pre-creation matrix (aws-build.md:59-89 — on an EKS page), the IAM CLI narration (109-132, replaceable with one AWS link), and the SMTP table (configure-wave.md:99-109). Beyond that: Bottlerocket and "Production enhancements" belong in troubleshoot / the existing checklist, IRSA is explained three times across two files, and configure-wave.md documents an EC2 instance profile for Docker-based builds that index.md:23 says aren't supported.
A stacked PR against this branch follows with the fixes.
Follow-up to #1106. Addresses the review findings in three groups. Deployments that would not work as documented: - aws-build: scan was enabled without wave.scan.reports.path. The bean factory throws on a null path and Application starts Micronaut with eagerInitSingletons(true), so Wave failed to boot. - aws-build: wave-build-pvc existed only in the `wave` namespace while build jobs run in `wave-build`. PVCs are namespaced, so every build, scan, and mirror pod stayed Pending. Now created in both. - aws-build: added the missing `noarch` node selector key. Without it getNoArchSelector returns an empty map and mirror and blob cache pods schedule outside the build node group. - aws-build: the S3 bucket referenced by the IAM policy and the build logs and locks paths is now created, and listed as a requirement. - aws-build: restored WAVE_JVM_OPTS. launch.sh defaults to -Xmx850m regardless of the 4Gi container limit. - docker-compose: DOCKER_USER and DOCKER_PAT are not read by Wave. They work only where config.yml interpolates them, and this guide replaces the config.yml that does. Moved into wave.registries. - kubernetes-lite: the registry snippet was a second top-level `wave:` block, which would drop wave.db.* and wave.server.url. Folded into the single ConfigMap. - kubernetes-lite: added the missing `kubectl apply` step, and completed the ALB ingress with ingressClassName and annotations so the /service-info check in post-install can pass. - Restored the endpoints.health guard dropped from master. jdbc and disk-space are on by default, so a brief Postgres blip turned the liveness probe red. - configure-wave: the MICRONAUT_ENVIRONMENTS examples re-added `lite`, which gates out JobManager and cleanup via @requires(missingBeans). - reference: restored kebab-case on six keys the merge reverted to camelCase, undoing #1096 - they still bind from YAML but lose env-var overridability. - Production checklist now uses wave.capabilities.anonymous-access instead of the wave.allowAnonymous legacy alias, and mentions the strict environment. - Fixed how-wave-works link to the renamed configuration reference. Simplification, per the review rubric: - Moved the seven-registry pre-creation matrix out of the EKS guide and into the reference. - Moved Bottlerocket user-namespace setup to troubleshoot. - Cut the SMTP settings table, the duplicate ECR cache walkthrough, the third IRSA explanation, and the EC2-instance-profile section for Docker builds, which the install paths do not support. - Trimmed the IAM narration to the Wave-specific delta and linked the AWS IRSA procedure. - Dropped "Production enhancements", keeping build-pod egress as a checklist item. - Made the sizing prerequisites per-replica so they match the manifests. Reference and verification: - Added wave.build.enabled, wave.mirror.enabled, wave.blob-cache.enabled, wave.job-manager.max-running-jobs and the mail.smtp.* keys; finished the truncated wave.accounts entry; corrected five (required) labels on settings that ship defaults. - post-install now covers the mirror and scan checks for the features aws-build enables. - Added troubleshoot to the sidebar and gave it front matter; moved post-install ahead of aws-build. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Thanks @pditommaso - changes are merged with a lite deslop/style guide |
No description provided.