From 96354831003ee1d440df9d947788c4d1da6e973b Mon Sep 17 00:00:00 2001 From: nexus Date: Fri, 29 May 2026 23:18:52 +0800 Subject: [PATCH 1/2] fix(ami): move first-boot admin credentials to /root (0600, root-only) AWS Marketplace AMI policy requires default admin credentials to be generated on first boot (not baked into the AMI) and stored as a read-once file outside /var/log, mode 0600, owned by root only, with instructions to delete after first read. - first-boot-db.sh: write /root/nexus-admin-credentials.txt (was /var/log/nexus/admin-credentials.txt), chmod 0600 + chown root:root, update the in-file IMPORTANT note and /etc/motd - harden.sh: wipe the new /root path at build time (kept the legacy /var/log wipe defensively) so no copy is baked into the image - nexus-ami/README.md: point the manual-test step at the new path Co-Authored-By: Claude Opus 4.8 (1M context) --- .../deployment/ami-appliance-architecture.md | 260 ------------------ docs/operators/ops/ami-build.md | 81 ------ nexus-ami/README.md | 7 +- nexus-ami/scripts/first-boot-db.sh | 20 +- nexus-ami/scripts/harden.sh | 5 + 5 files changed, 22 insertions(+), 351 deletions(-) delete mode 100644 docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md delete mode 100644 docs/operators/ops/ami-build.md diff --git a/docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md b/docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md deleted file mode 100644 index 473f2862..00000000 --- a/docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -updated: 2026-05-28 ---- - -# AMI / appliance deployment architecture - -Single-box deployment form factor for Nexus Gateway. Packages **all** runtime -dependencies (PostgreSQL 16, Valkey 8 with `valkey-search`, NATS JetStream, -4 Go services, the React UI, and an nginx reverse proxy) into one disk image -managed by systemd. The same artifacts ship as: - -| Target | Wrapped by | -|---|---| -| **AWS Marketplace AMI** | `nexus-ami/nexus.pkr.hcl` (Packer + Amazon Linux 2023) | -| **VMware / KVM image** | future — same `install.sh`, different Packer builder | -| **Bare-metal appliance** | future — same `install.sh` invoked from a kickstart / preseed | - -This doc is the architecture source of truth for **everything under -`nexus-ami/`**. Any change to a config file, systemd unit, install script, -or first-boot script in that directory MUST update this doc in the same -commit (Code/Doc Lockstep — see `.cursor/rules/code-doc-lockstep.mdc`). - -## 1. Why one form factor for AMI + bare-metal - -Two distribution channels share the same install logic: - -- **Cloud appliance** — AWS Marketplace AMI (initial target). Customer hits - "Launch", gets a working single-instance Nexus in ~5 minutes. -- **On-prem appliance** — pre-installed disk image / ISO for hardware - shipped to customer sites (future). Same systemd-managed services, same - first-boot secret generation. - -Containerised / Kubernetes deployment is **out of scope** for this doc. If -the project later ships a Helm chart or container Marketplace listing, that -is a separate architecture (`-container-architecture.md`) with its -own dependency wiring (RDS / ElastiCache / managed MQ). - -## 2. Boot sequence (every fresh instance / fresh hardware) - -``` -1. cloud-init / kickstart → network + ec2-user / nexus shell login -2. firewalld → open 443, 3128, 22; close everything else -3. nexus-first-boot.service → oneshot, gated by /etc/nexus/.initialized - ├─ first-boot-secrets.sh → generate 5 [MUST MATCH] secrets, write - │ /etc/nexus/{nexus-hub,control-plane, - │ ai-gateway,compliance-proxy}.env - ├─ first-boot-ca.sh → generate compliance-proxy MITM CA at - │ /etc/compliance-proxy/{ca.crt,ca.key} - └─ first-boot-db.sh → start postgresql, wait, prisma db push, - prisma db seed, randomise admin password, - write /var/log/nexus/admin-credentials.txt - and /etc/motd -4. postgresql.service → After=nexus-first-boot -5. valkey.service → After=nexus-first-boot -6. nats.service → After=nexus-first-boot -7. nexus-hub.service → After=postgresql valkey nats -8. nexus-control-plane.service → After=nexus-hub -9. nexus-gateway.service → After=nexus-hub -10. nexus-proxy.service → After=nexus-hub -11. nginx.service → After=nexus-control-plane (reverse proxy) -``` - -`/etc/nexus/.initialized` is the idempotency marker. Removing it triggers a -fresh init on next boot (destructive — generates new secrets, re-seeds DB). -Customers should never touch it. - -## 3. Filesystem layout - -| Path | Owner | Mode | Contents | -|---|---|---|---| -| `/opt/nexus/bin/` | root:root | 0755 | 4 Go service binaries (immutable, part of AMI) | -| `/opt/nexus/ui/` | root:root | 0755 | Vite-built UI dist (immutable, part of AMI) | -| `/opt/nexus/prisma/` | root:root | 0755 | Prisma schema + seed (immutable, part of AMI) | -| `/etc/nexus/` | root:nexus | 0750 | 4 prod-shape `*.config.yaml` + 4 `*.env` + nginx-nexus.conf + `.initialized` marker | -| `/etc/compliance-proxy/` | root:nexus | 0750 | MITM CA cert + key (generated first-boot) | -| `/var/lib/nexus/` | nexus:nexus | 0750 | Service runtime state (agent CA dir, NDJSON spool, file-backed alerting state) | -| `/var/lib/postgresql/data/` | postgres:postgres | 0700 | PostgreSQL data directory (AL2023 dnf default) | -| `/var/lib/valkey/` | valkey:valkey | 0750 | Valkey AOF + RDB | -| `/var/lib/nats/` | nats:nats | 0750 | NATS JetStream file store | -| `/var/log/nexus/` | nexus:nexus | 0750 | Service log files (rotated by logrotate); also holds `admin-credentials.txt` (mode 0640, root:nexus) | - -## 4. Secret generation (`first-boot-secrets.sh`) - -Five environment variables MUST be unique-per-instance and identical across -the four services that share them (see `.env.example` `[MUST MATCH]` tags): - -| Env var | Used by | Generation | -|---|---|---| -| `INTERNAL_SERVICE_TOKEN` | all 4 | `openssl rand -hex 32` | -| `ADMIN_KEY_HMAC_SECRET` | control-plane, ai-gateway | `openssl rand -hex 32` | -| `CREDENTIAL_ENCRYPTION_KEY` | control-plane, ai-gateway | `openssl rand -hex 32` (AES-256, 64 hex chars) | -| `COMPLIANCE_PROXY_API_TOKEN` | control-plane, compliance-proxy | `openssl rand -hex 32` | -| `AI_GATEWAY_API_TOKEN` | ai-gateway only | `openssl rand -hex 32` | - -Each is written to the appropriate per-service `.env` file under `/etc/nexus/` -which the systemd unit picks up via `EnvironmentFile=`. File mode `0640`, -owner `root:nexus` (services run as `nexus` and read; only root can rewrite). - -`DATABASE_URL`, `REDIS_ADDRS`, `NATS_URL`, `NEXUS_HUB_URL`, -`AUTH_SERVER_URL`, `AUTH_SERVER_JWKS_URL`, `AUTH_SERVER_ISSUER`, -`AI_GATEWAY_URL`, `COMPLIANCE_PROXY_URL`, `COMPLIANCE_PROXY_RUNTIME_URL` — -all bind to `localhost` with fixed ports (see §6), baked into the per-service -`.env` files at first boot. - -## 5. Database initialisation (`first-boot-db.sh`) - -1. `systemctl start postgresql` (synchronous via `--wait`). -2. `psql` create role `nexus` with a per-instance random password; create - database `nexus_gateway` owned by `nexus`. -3. Write the matching `DATABASE_URL=postgresql://nexus:@localhost:5432/nexus_gateway?sslmode=disable` - into every `*.env` file under `/etc/nexus/`. -4. `cd /opt/nexus/prisma && npx prisma db push --skip-generate` to materialise - the schema (no migration history table — fresh instance, no upgrade path - to preserve). -5. `npx tsx seed/seed.ts` to load baseline rows (organisations, IAM, - roles, default settings — see `tools/db-migrate/seed/seed.ts`). -6. Generate a 24-character random admin password, hash it with the same - scrypt parameters the seed uses (`tools/db-migrate/seed/lib.ts` - `hashPassword()` — N=16384, r=8, p=1, salt=32, key=64), and - `UPDATE "NexusUser" SET "passwordHash" = $1 WHERE email = 'admin@nexus.ai'`. -7. Write the plaintext password + login URL + warning to - `/var/log/nexus/admin-credentials.txt` (mode 0640, root:nexus) and append - a one-screen summary to `/etc/motd` so the operator sees it on first SSH. - -`admin@nexus.ai` is the only seeded user that ships with a password. All -other seeded users (alice / bob / carol / diana etc., listed in -`packages/control-plane-ui/README.md`) keep their dev-time passwords from -the seed and are documented as "demo accounts — disable for production" -in the operator-facing docs. - -## 6. Port map (all bound to `localhost` except nginx + compliance-proxy) - -| Port | Service | Binding | Exposed via firewall? | -|---|---|---|---| -| 5432 | PostgreSQL | localhost:5432 | no | -| 6379 | Valkey | localhost:6379 | no | -| 4222 | NATS client | localhost:4222 | no | -| 8222 | NATS HTTP monitoring | localhost:8222 | no | -| 3060 | Nexus Hub | localhost:3060 | no | -| 3001 | Control Plane API | localhost:3001 | no (nginx proxies `/api/*`) | -| 3050 | AI Gateway | 0.0.0.0:3050 | **yes** (SDK clients hit this directly) | -| 3040 | Compliance Proxy runtime API | localhost:3040 | no | -| 3128 | Compliance Proxy CONNECT | 0.0.0.0:3128 | **yes** (network-proxied apps) | -| 9090 | Prometheus metrics | localhost:9090 | no | -| 443 | nginx (UI + `/api/*` reverse proxy) | 0.0.0.0:443 | **yes** | -| 22 | sshd | 0.0.0.0:22 | yes (Marketplace standard) | - -The compliance-proxy CA file path (`/etc/compliance-proxy/ca.crt`, -`/etc/compliance-proxy/ca.key`) is hardcoded into the prod-shape config -because the path is also baked into the systemd unit's `ReadWritePaths` and -into the `first-boot-ca.sh` generator — three places must agree. - -## 7. Hardening (`harden.sh`) - -Runs as the **last** Packer provisioner (after `install.sh`). Standard -AWS Marketplace AMI cleanup; without this the AMI fails the Self-Service -Scan and is rejected on submission. - -| Action | Why | -|---|---| -| `rm -f /root/.ssh/authorized_keys /home/*/.ssh/authorized_keys` | No shared SSH keys (customers BYO) | -| `rm -f /etc/ssh/ssh_host_*` | Regenerated on first boot — no shared host keys across instances | -| `sed -i sshd_config` (PasswordAuthentication=no, PermitRootLogin=no) | Hard requirement for AWS Marketplace | -| `passwd -l root` | Lock root password | -| `find / -name authorized_keys -delete` | Recursive scrub | -| `rm -rf /var/lib/postgresql/data/* /var/lib/valkey/* /var/lib/nats/*` | Clear any pg/valkey/nats state accumulated during install validation | -| `truncate -s 0 /etc/machine-id` | Regenerated on first boot | -| `cloud-init clean --logs` | Fresh cloud-init state | -| `dnf clean all` | Shrink AMI size | -| `find /var/log -type f -exec truncate -s 0 {} \;` | No leaked build-time logs | -| `dd if=/dev/zero of=/zerofile && rm /zerofile && sync` | Free-space zeroing — EBS snapshot dedupes better | - -## 8. AMI build pipeline (`nexus-ami/build.sh` → `nexus.pkr.hcl`) - -``` -make build-all → dist/bin// (4 Go binaries) -make control-plane-ui-build → packages/control-plane-ui/dist/ -build.sh stages → nexus-ami/artifacts/ → flatten + copy + tar -packer init . && packer build → AMI ID in us-east-1 -``` - -Packer steps: - -1. Launch an `m5.4xlarge` builder instance (16 vCPU / 64 GB) from the - latest Amazon Linux 2023 AMI. **Must be `m5.4xlarge` (or larger), not - `t3.2xlarge`** — valkey-search 1.x vendors gRPC + Protobuf + Abseil - + ICU as submodules; template-heavy parallel C++ compile is heap-hungry - per translation unit. Empirically, `t3.2xlarge` (32 GB) is OOM-killed - silently mid-ICU-compile after ~11 minutes (kernel OOM-killer kills sshd - before the script can write stderr — no trace in Packer build logs); - 64 GB clears the failure mode. 2026-05-28 build evidence. -1a. **Linker = lld, not GNU ld.** `install-valkey.sh` installs `lld${ver}` - alongside `clang${ver}` and exports `LDFLAGS=-fuse-ld=lld` before - invoking valkey-search's `./build.sh`. Reason: valkey-search compiles - with `-flto`, and linking `libsearch.so` requires LTO bitcode handling. - GNU ld delegates LTO to the LLVMgold.so plugin, but AL2023's `clang20` - package **omits** LLVMgold.so (verified 2026-05-28: link failed with - `cannot open /usr/lib64/llvm20/lib64/LLVMgold.so`). lld is LLVM's - native linker and handles LTO bitcode directly without a plugin. -2. `file` provisioner uploads `nexus-ami/artifacts.tar.gz` (single file, - ~120 MB) to `/tmp/nexus-artifacts.tar.gz`. We deliberately do NOT upload - `artifacts/` as a directory — Packer's file provisioner uses recursive - SCP under the hood, which silently drops individual files on slow links - (a problem we hit on China → us-east-1 at ~250 KB/s). A single-file - transfer is atomic and fails loudly. -3. `shell` provisioner runs `scripts/install.sh`. The script first extracts - the tarball to `/tmp/nexus/`, then (~10 minutes total) installs - Postgres, builds Valkey from source, installs NATS, installs Node + - Prisma, places binaries + configs + systemd units. -4. `shell` provisioner runs `scripts/harden.sh` (~30 seconds). -5. Packer snapshots the EBS root volume → registers the AMI. - -Total build time: 15–20 minutes per region (on good links; -+5–10 minutes for the cross-Pacific tarball upload from China). - -## 9. Instance sizing recommendation (Marketplace listing) - -| Tier | Instance type | When | -|---|---|---| -| Minimum | `t3.large` (2 vCPU / 8 GB) | PoC, ≤ 100 traffic events/hour | -| Recommended | `t3.xlarge` (4 vCPU / 16 GB) | Small production, ≤ 10k events/hour | -| Performance | `m5.2xlarge` (8 vCPU / 32 GB) | Production, ≤ 100k events/hour | - -Root volume: **≥ 30 GiB** (Postgres + Valkey + NATS file store + log -retention). Marketplace listing should state this requirement explicitly. - -## 10. Out of scope (intentionally) - -- **HA / multi-instance** — by design single-instance. Customers wanting HA - use the Kubernetes / container deployment form factor (separate listing). -- **Schema migration across versions** — pre-GA policy is "fresh install - on every AMI version bump"; customers re-launch a new AMI and re-load - their data via the admin API. Documented as an evaluation product in - the Marketplace listing. -- **External SSO** — AMI ships with the embedded auth server bound to - `localhost`; OIDC federation requires the customer to edit - `/etc/nexus/control-plane.config.yaml` `authServer:` block and restart - the service. -- **TLS termination on a real domain** — AMI ships nginx with a self-signed - cert generated at first boot; documented as "replace with your domain's - cert in `/etc/nexus/tls.{crt,key}` and restart nginx". -- **Agent fleet enrollment from this AMI** — works, but the agent's - bootstrap URL needs to be reachable from the agent host; this is a - network-topology concern documented in the user-facing deployment guide, - not an AMI-side decision. - -## 11. Memory anchors - -- `[[ami_first_boot_5_secrets]]` — five `[MUST MATCH]` secrets must be - written before any Nexus service starts, or services 401 each other. -- `[[ami_random_admin_password_marketplace_safe]]` — random per-instance - admin password is the cheapest defence against the AWS Marketplace - default-credentials finding category. - -## 12. Related docs - -- `.env.example` — canonical env var contract (the AMI honours every - `[MUST MATCH]` tag). -- `docs/developers/architecture/cross-cutting/foundation/configuration-architecture.md` — 4-layer config model the AMI plugs into at L2 (yaml) + L3 (env). -- `nexus-ami/README.md` — operator-facing build / test / publish runbook. diff --git a/docs/operators/ops/ami-build.md b/docs/operators/ops/ami-build.md deleted file mode 100644 index c845af22..00000000 --- a/docs/operators/ops/ami-build.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -updated: 2026-05-29 ---- - -# AMI build (single-instance appliance) - -How to build the AWS Marketplace AMI / single-instance appliance image. The -source-of-truth for everything in this guide is [`nexus-ami/README.md`](../../../nexus-ami/README.md); -the design rationale is captured in -[`docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md`](../../developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md). - -## When to use this - -- Cutting a release for the AWS Marketplace listing. -- Producing an image for an on-prem customer that wants a single-VM install. -- Smoke-testing a Packer / install-script change before publishing. - -## Prerequisites - -- Go 1.25+, Node 20+, Packer 1.10+. -- AWS credentials with `AWS_PROFILE=` exporting EC2 + S3 + IAM - permissions in `us-east-1`. -- A `t3.medium` or larger key pair on the target account if you intend to - launch instances from the AMI after build. -- vCPU headroom: the build runs on an `m5.4xlarge` (16 vCPU). If the - Standard-family quota is 16 and another instance is already running, stop - it or request a quota bump first (otherwise Packer fails immediately with - `VcpuLimitExceeded`). - -## Build - -```bash -cd nexus-ami -./build.sh # full pipeline (compile + stage + packer build, ~55 min) -./build.sh --skip-packer # CI dry-run — stage only, skip the EC2 launch -``` - -A successful build prints the new AMI id (e.g. `ami-0xxxxxxxx`) and a -snapshot id. - -## After the build - -1. **Share with the Marketplace scanner** (account `679593333241`): - - ```bash - aws ec2 modify-image-attribute --image-id \ - --launch-permission "Add=[{UserId=679593333241}]" \ - --profile --region us-east-1 - aws ec2 modify-snapshot-attribute --snapshot-id \ - --create-volume-permission "Add=[{UserId=679593333241}]" \ - --profile --region us-east-1 - ``` - -2. **Trigger the AMI scan** in Partner Central → AMI Management Portal. - -3. **Test the AMI**: - - ```bash - aws ec2 run-instances --image-id --instance-type t3.medium \ - --key-name --associate-public-ip-address \ - --profile --region us-east-1 - # SSH in, then: sudo cat /var/log/nexus/admin-credentials.txt - ``` - - Two instances launched from the same AMI MUST have different admin - passwords — that is the most important first-boot invariant. - -## Common failure modes - -| Symptom | Root cause | Fix | -|---|---|---| -| `VcpuLimitExceeded` immediately at `packer build` | Standard-family quota hit because another instance is running | Stop or terminate it, or request a quota raise | -| `Script disconnected unexpectedly` mid-Valkey compile | Build host OOM-killed sshd | Default is `m5.4xlarge`; do not lower | -| `InvalidParameterValue: Character sets beyond ASCII are not supported` at `Modifying attributes on AMI` | Non-ASCII in `ami_description` (e.g. em dash) | Keep `nexus.pkr.hcl` `ami_description` ASCII-only | -| First-boot completes but 4 nexus-* services stay `inactive` | Boot-order race — nexus-* tried to start before postgres was up | Already handled by `first-boot.sh`'s tail `kick` block | - -## Iteration cadence - -Plan a **monthly rebuild** to absorb AL2023 + Postgres + Valkey + NATS CVE -patches. `./build.sh` is the single command; wire it into a CI cron once -the AMI is stabilised. diff --git a/nexus-ami/README.md b/nexus-ami/README.md index d960dffe..89731d10 100644 --- a/nexus-ami/README.md +++ b/nexus-ami/README.md @@ -54,8 +54,9 @@ Output: a registered AMI ID in your AWS account (region per # 2. SSH in with your EC2 key pair: ssh -i ~/.ssh/your-key.pem ec2-user@ -# 3. Read the per-instance admin credentials: -sudo cat /var/log/nexus/admin-credentials.txt +# 3. Read the per-instance admin credentials (generated on first boot, +# mode 0600, root-only — delete after first read): +sudo cat /root/nexus-admin-credentials.txt # 4. Verify all 7 Nexus-related services are green: systemctl status nexus-first-boot postgresql valkey nats \ @@ -65,7 +66,7 @@ systemctl status nexus-first-boot postgresql valkey nats \ # log in with the credentials from step 3. # 6. Launch a SECOND instance from the same AMI and confirm -# /var/log/nexus/admin-credentials.txt contains a DIFFERENT password. +# /root/nexus-admin-credentials.txt contains a DIFFERENT password. # Per-instance secret uniqueness is the most important first-boot invariant. ``` diff --git a/nexus-ami/scripts/first-boot-db.sh b/nexus-ami/scripts/first-boot-db.sh index 21bd53c7..56e04cbe 100755 --- a/nexus-ami/scripts/first-boot-db.sh +++ b/nexus-ami/scripts/first-boot-db.sh @@ -17,7 +17,11 @@ set -euo pipefail export PATH=/opt/nexus/node/bin:$PATH PRISMA_DIR=/opt/nexus/prisma -ADMIN_CREDS=/var/log/nexus/admin-credentials.txt +# AWS Marketplace AMI policy: default admin credentials must be generated on +# first boot (never baked into the AMI), and the read-once file must live +# outside /var/log, be mode 0600, and be owned by root only. /root satisfies +# this — see ami-appliance-architecture.md §5. +ADMIN_CREDS=/root/nexus-admin-credentials.txt # Source the per-service env file written by first-boot-secrets.sh — the seed # requires CREDENTIAL_ENCRYPTION_KEY (re-encrypts seeded credential rows) and @@ -153,9 +157,10 @@ Password: $ADMIN_PASSWORD IMPORTANT --------- -1. This file is mode 0640, root:nexus — root or members of the 'nexus' group - can read it. Remove this file once you have changed the admin password - from the UI: sudo rm $ADMIN_CREDS +1. This file is mode 0600, owned by root — only root can read it. It was + generated on first boot and is unique to this instance. Delete it as soon + as you have logged in and changed the admin password from the UI: + sudo rm $ADMIN_CREDS 2. The TLS certificate at /etc/nexus/tls.crt is SELF-SIGNED. Replace it with a cert signed for your hostname before exposing the appliance publicly, then run: sudo systemctl reload nginx @@ -169,17 +174,18 @@ For full operator documentation see: https://github.com/AlphaBitCore/nexus-gateway/blob/main/docs/operators/ ================================================================================ EOF -chmod 0640 "$ADMIN_CREDS" -chown root:nexus "$ADMIN_CREDS" +chmod 0600 "$ADMIN_CREDS" +chown root:root "$ADMIN_CREDS" cat > /etc/motd < [harden] clearing per-stateful service data accumulated during install # install-time content baked into the AMI is a leak / non-determinism source. rm -rf /var/lib/pgsql/data/* /var/lib/valkey/* /var/lib/nats/* 2>/dev/null || true rm -f /etc/nexus/.initialized 2>/dev/null || true +# Per-instance admin credentials are generated on first boot, never baked into +# the AMI. Wipe both the current path and the legacy /var/log location so no +# build-time test artifact can leak into the published image (AWS Marketplace +# AMI policy: no hardcoded/shared credentials in the AMI). +rm -f /root/nexus-admin-credentials.txt 2>/dev/null || true rm -f /var/log/nexus/admin-credentials.txt 2>/dev/null || true echo "==> [harden] zeroing free space (shrinks EBS snapshot)..." From 371848b21d0f7fefcae35b9b11d83e639be659ce Mon Sep 17 00:00:00 2001 From: nexus Date: Fri, 29 May 2026 23:19:06 +0800 Subject: [PATCH 2/2] docs: fix repo URL in README badges; drop nexus-ami from public docs - README.md: CI/Go-CI badge links pointed at the placeholder your-org/abc-nexus-gateway; repoint at AlphaBitCore/nexus-gateway. Remove the AWS Marketplace AMI and bare-metal-appliance rows from the Deployment table. - docs/operators/README.md: drop the ami-build.md index entry. - docs/developers/architecture/README.md: remove the now-empty "Cross-cutting - deployment" trigger-map section. - Makefile, .gitignore: drop comment lines citing the deleted AMI architecture doc (build targets / ignore rules kept). The AMI/appliance form factor stays a working build dir under nexus-ami/ but is no longer advertised in the public README, docs, or wiki. Verified: check:arch-doc-triggers OK, check:doc-lockstep clean, and no nexus-ami / ami-build / ami-appliance references remain in README or docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 3 +-- Makefile | 5 ++--- README.md | 8 +++----- docs/developers/architecture/README.md | 6 ------ docs/operators/README.md | 1 - 5 files changed, 6 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index 905585fe..ca3a0d46 100644 --- a/.gitignore +++ b/.gitignore @@ -3,8 +3,7 @@ dist/ # nexus-ami staging artifacts populated by nexus-ami/build.sh — the binaries, # UI dist, and Prisma bundle are derived from the source tree on every build -# and should never be committed. Architecture: -# docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md +# and should never be committed. See nexus-ami/README.md for the build flow. nexus-ami/artifacts/bin/ nexus-ami/artifacts/ui-dist/ nexus-ami/artifacts/prisma/ diff --git a/Makefile b/Makefile index bda5b8d1..18341844 100644 --- a/Makefile +++ b/Makefile @@ -134,10 +134,9 @@ agent-package-windows: agent-build-windows agent-clean-windows: rm -rf dist/windows -# ── AMI / appliance build (E-OSS marketplace) ──────────────────────── +# ── AMI / appliance build ──────────────────────────────────────────── # Wraps Go binaries + UI dist + Prisma bundle + Packer build into one -# invocation. Architecture: -# docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md +# invocation. See nexus-ami/README.md for the build / publish runbook. ami-build: bash nexus-ami/build.sh diff --git a/README.md b/README.md index d545f96b..cea2d519 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Nexus Gateway -[![CI](https://github.com/your-org/abc-nexus-gateway/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/your-org/abc-nexus-gateway/actions/workflows/ci.yml) -[![Go CI](https://github.com/your-org/abc-nexus-gateway/actions/workflows/go-ci.yml/badge.svg?branch=main)](https://github.com/your-org/abc-nexus-gateway/actions/workflows/go-ci.yml) +[![CI](https://github.com/AlphaBitCore/nexus-gateway/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/AlphaBitCore/nexus-gateway/actions/workflows/ci.yml) +[![Go CI](https://github.com/AlphaBitCore/nexus-gateway/actions/workflows/go-ci.yml/badge.svg?branch=main)](https://github.com/AlphaBitCore/nexus-gateway/actions/workflows/go-ci.yml) [![Coverage gate](https://img.shields.io/badge/coverage-%E2%89%A595%25%20per%20package-brightgreen)](./scripts/check-go-coverage.sh) [![Status: Pre-GA](https://img.shields.io/badge/status-Pre--GA%20%C2%B7%20active%20development-orange)](./CHANGELOG.md) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE) @@ -119,10 +119,8 @@ The lateral dotted arrow is the **attestation handoff**: the Agent always egress | Form factor | How | Status | |---|---|---| -| **AWS Marketplace AMI / single-instance appliance** | `cd nexus-ami && ./build.sh` — bakes binaries + UI + Prisma + nginx + Postgres + Valkey + NATS into one AL2023 image via Packer | [`nexus-ami/README.md`](./nexus-ami/README.md) for build steps, [`docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md`](./docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md) for design | | **Local development** | docker-compose + `./scripts/dev-start.sh` (Postgres + Valkey + NATS) and per-service `go run ./cmd//` | See **Quick start** below | -| **VMware / KVM image / bare-metal appliance** | Reuses the same `install.sh` + `harden.sh` from `nexus-ami/scripts/` under a different Packer builder | Future | -| **Container / Kubernetes** | Out of scope for the appliance form factor — separate product line | Future | +| **Container / Kubernetes** | Container images per service — separate product line | Future | --- diff --git a/docs/developers/architecture/README.md b/docs/developers/architecture/README.md index baf94391..9cc3866a 100644 --- a/docs/developers/architecture/README.md +++ b/docs/developers/architecture/README.md @@ -168,12 +168,6 @@ If you are about to edit code in an area that is genuinely **not** covered by an | i18n keys (`t('namespace:section.key')`), locale files (`packages/*/src/i18n/locales/**`), `packages/ui-shared/src/i18n/**` | `docs/developers/architecture/cross-cutting/ui/ui-i18n-architecture.md` | | `useApi` / `useApiMutation` hooks + queryKey shape, `shellRouteConfig.tsx` / `Sidebar.tsx` IA, `packages/ui-shared/**` cross-bundle components | `docs/developers/architecture/cross-cutting/ui/ui-shell-architecture.md` | -## Cross-cutting — deployment - -| Editing area / file glob | Read FIRST | -|---|---| -| `nexus-ami/**` — Packer template, install / first-boot / harden scripts, prod-shape `*.config.yaml`, systemd unit files for the AMI / bare-metal appliance form factor | `docs/developers/architecture/cross-cutting/deployment/ami-appliance-architecture.md` | - ## Adding a new arch doc When you ship a new `docs/developers/architecture/**/*-architecture.md`: diff --git a/docs/operators/README.md b/docs/operators/README.md index a092ea59..67ed22c7 100644 --- a/docs/operators/README.md +++ b/docs/operators/README.md @@ -6,7 +6,6 @@ Documentation for running Nexus Gateway in production. - [`ops/`](./ops/) — deployment and operations guides: - [`deployment.md`](./ops/deployment.md) — bring-up and topologies. - - [`ami-build.md`](./ops/ami-build.md) — build the single-instance appliance AMI (AWS Marketplace). - [`ec2-single-node.md`](./ops/ec2-single-node.md) — a single-node deployment. - [`install-test-env.md`](./ops/install-test-env.md) — a single-host test or staging install. - [`backup-dr.md`](./ops/backup-dr.md) — backup and disaster recovery.