Repository navigation
docs: correct the quick start, monitoring commands, backend count and design index - #668
Open
LeeroyHannigan wants to merge 1 commit into
Open
LeeroyHannigan wants to merge 1 commit into
LeeroyHannigan wants to merge 1 commit into
Conversation
… design index The README quick start ran aws dynamodb list-tables without credentials, and the AWS CLI stopped with "Unable to locate credentials". The quick start now creates an IAM user, attaches a policy that allows DynamoDB, creates an access key with extenddb manage, and exports the key before the request. A key this server did not issue gets UnrecognizedClientException, so configured AWS credentials do not help. /metrics requires admin HTTP Basic auth and answers 401 without it. The metrics commands in the README, the admin guide and the event ticketing demo now pass the admin credentials, and the deployment guide's monitoring checklist says the poller needs them. The demo's metrics and console URLs had **18443** as the port, which curl refuses, so the asterisks are removed. The README crate list, the architecture guide overview and the storage design status line named PostgreSQL as the only backend. They now name the four backends in crates/: PostgreSQL, SQLite, MongoDB and Cassandra. The design index linked version 2.0 of the auth design, which 05-component-auth-v3.md supersedes. The index row now links version 3 and names version 2.0 as superseded. #530 corrects the README feature list and use cases, which also named PostgreSQL as the only database. #523 replaces the getting started page and the install manuals, whose backend lists and smoke tests have the same gaps. Refs #663
LeeroyHannigan
requested review from
amrith,
c33howard,
jcshepherd,
pdf-amzn,
robinnsc and
yesyayen
as code owners
October 29, 2026 23:59
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
This branch fixes the four documentation problems #663 lists. Some of the same
problems also appear in pages that #523 and #530 already change; those are left
to those PRs and named under each item.
README quick start
The quick start ran
aws dynamodb list-tablesright afterserve. Requestsmust be signed with an access key this server issued, and nothing in the quick
start created one, so the AWS CLI stopped with
Unable to locate credentials(exit 255). A reader who already has AWS credentials configured gets
UnrecognizedClientExceptioninstead, because the server does not know thosekeys.
The quick start now creates an IAM user, attaches a policy that allows
dynamodb:*, and creates an access key for the user withextenddb manage,using the admin password and the account ID that
initprints. It then setsAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYto theaccess_key_idandsecret_access_keythatcreate-access-keyprints. These are the admincommands
docs/local-dev-docker-compose.mdalready uses.The Linux and macOS install manuals and the MongoDB setup page also run
list-tableswith no key. #523 removes those pages, and itsdocs/install-from-source.mdcreates the key before the first request.Monitoring commands
/metricsrequires an admin user's name and password as HTTP Basic auth andanswers 401
Missing Authorization headerwithout them. Thecurlcommandsin the README, the admin guide and the event ticketing demo sent none. They now
pass
-u admin:<password>(the demo reads theEXTENDDB_ADMIN_PASSWORDitexports in step 3), and the deployment guide's monitoring checklist says the
poller needs the admin credentials. Step 13 of the demo also wrote the port as
**18443**inside a code block. curl refuses that URL (exit 3), so theasterisks are removed from both URLs in that step.
/health,extenddb statusandextenddb healthcheckwork as written and areunchanged.
Backend count
The README crate list, the architecture guide overview ("currently
PostgreSQL") and the storage design's status line ("PostgreSQL is the only
supported backend") named PostgreSQL as the only backend. They now name the
four backends in
crates/: PostgreSQL, SQLite, MongoDB and Cassandra. TheREADME crate list is realigned because
storage-cassandra/is wider than theold column, and it now separates names from descriptions with spaces, as the
architecture guide's crate tree does. No support tiers are added; #662 covers
those.
#530 corrects the README feature list and the multi-cloud use case, which also
named PostgreSQL alone. #523 replaces
docs/getting-started.md, whose buildcommands and feature list leave out Cassandra.
Design index
docs/design/README.mdlinked version 2.0 of the auth design(
05-component-auth.md). Version 3 (05-component-auth-v3.md) states that itsupersedes version 2.0. The index row now links version 3 and links version 2.0
as superseded.
How it was measured
The measurements ran on a release build of
mainat 817b240 (cargo build --release -p extenddb, the PostgreSQL backend) against PostgreSQL 16 in acontainer, in a clean
HOMEand an environment with no AWS settings.initwas given the container's host and port, and the server listened on port 15740
in place of 18443; the other commands ran as the docs write them.
aws dynamodb list-tablesUnable to locate credentials, exit 255{"TableNames": []}, exit 0curl ... /metrics(README, admin guide)Missing Authorization headercurl ... | python3 -m json.toolcurl ... | python3 -c ...JSONDecodeErrorcurl ... /healthThe corrected quick start then ran end to end in a fresh
HOMEagainst a freshdatabase, and
list-tablesreturned an empty table list. The AWS CLI on thebuild host is 1.18.147; the docs name version 2, which was not run.
Testing
tests/cli/test-doc-consistency.shreports the same 110 failures onmainand on this branch.
cargo test --release -p extenddb-storage-postgres --test doc_version_literalspasses (3 tests).The change is documentation only. No Rust, workflow or test file changes.
Overlap with the open docs PRs
The one line this branch shares with #491, #523 and #530 is the first
paragraph of the architecture guide. Those PRs change its opening words, and
this branch changes the backend list at its end. Whichever merges second keeps
both changes. #666 does not overlap.
Refs #663