Skip to content

docs: correct the quick start, monitoring commands, backend count and design index - #668

Open
LeeroyHannigan wants to merge 1 commit into
mainfrom
docs/launch-prep-corrections
Open

LeeroyHannigan wants to merge 1 commit into
mainfrom
docs/launch-prep-corrections

Conversation

@LeeroyHannigan

Copy link
Copy Markdown
Collaborator

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-tables right after serve. Requests
must 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
UnrecognizedClientException instead, because the server does not know those
keys.

The quick start now creates an IAM user, attaches a policy that allows
dynamodb:*, and creates an access key for the user with extenddb manage,
using the admin password and the account ID that init prints. It then sets
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to the access_key_id and
secret_access_key that create-access-key prints. These are the admin
commands docs/local-dev-docker-compose.md already uses.

The Linux and macOS install manuals and the MongoDB setup page also run
list-tables with no key. #523 removes those pages, and its
docs/install-from-source.md creates the key before the first request.

Monitoring commands

/metrics requires an admin user's name and password as HTTP Basic auth and
answers 401 Missing Authorization header without them. The curl commands
in the README, the admin guide and the event ticketing demo sent none. They now
pass -u admin:<password> (the demo reads the EXTENDDB_ADMIN_PASSWORD it
exports 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 the
asterisks are removed from both URLs in that step.

/health, extenddb status and extenddb healthcheck work as written and are
unchanged.

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. The
README crate list is realigned because storage-cassandra/ is wider than the
old 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 build
commands and feature list leave out Cassandra.

Design index

docs/design/README.md linked version 2.0 of the auth design
(05-component-auth.md). Version 3 (05-component-auth-v3.md) states that it
supersedes 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 main at 817b240 (cargo build --release -p extenddb, the PostgreSQL backend) against PostgreSQL 16 in a
container, in a clean HOME and an environment with no AWS settings. init
was 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.

Command Before After
quick start aws dynamodb list-tables Unable to locate credentials, exit 255 {"TableNames": []}, exit 0
curl ... /metrics (README, admin guide) 401 Missing Authorization header 200 with the JSON metrics
demo step 13, curl ... | python3 -m json.tool curl exit 3 exit 0
demo step 23, curl ... | python3 -c ... 401, then JSONDecodeError exit 0, summary printed
curl ... /health 200 unchanged

The corrected quick start then ran end to end in a fresh HOME against a fresh
database, and list-tables returned an empty table list. The AWS CLI on the
build host is 1.18.147; the docs name version 2, which was not run.

Testing

  • No conflict markers in the tree.
  • The 45 relative links in the seven changed files resolve.
  • tests/cli/test-doc-consistency.sh reports the same 110 failures on main
    and on this branch.
  • cargo test --release -p extenddb-storage-postgres --test doc_version_literals passes (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

… 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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant