Repository navigation
docs: one install page per path, first requests page, container upgrades - #523
Open
LeeroyHannigan wants to merge 1 commit into
Open
LeeroyHannigan wants to merge 1 commit into
LeeroyHannigan wants to merge 1 commit into
Conversation
LeeroyHannigan
requested review from
c33howard,
jcshepherd,
pdf-amzn,
robinnsc and
yesyayen
as code owners
October 24, 2026 18:37
This was referenced Oct 24, 2026
LeeroyHannigan
force-pushed
the
feat/docs-site
branch
from
October 30, 2026 09:28
ceb6a63 to
eb8e221
Compare
Closes #492 and #495. The Install section had six pages that each cloned, built, initialized and started a server from source, with the platform packages, the TLS steps and the AWS CLI setup repeated on each, and a 1,461-line walkthrough that carried the manage command reference, runtime settings, external test suites and performance tuning beside the install steps. Two development notes on Contributing covered PostgreSQL and MongoDB setup a third time. Install section now: - docs/install-from-source.md: prerequisites, installer scripts, database install per platform (Ubuntu and Debian, Fedora and RHEL, Amazon Linux 2023 and 2, macOS with Homebrew; MongoDB as a replica set; Cassandra with PasswordAuthenticator), build per backend, init per backend, verify, serve, smoke test, upgrade after git pull, tear down, Linux and macOS differences, troubleshooting. Every command was run against a container of each backend with a binary built from this tree; the quoted output is from those runs. Two steps the old pages had wrong: MongoDB init reads the connection string from a seed extenddb.toml and needs --overwrite, and Cassandra init fails under the image's default AllowAllAuthenticator. - docs/first-requests.md: the walkthrough's operations (tables, items, query and scan, batches, transactions, streams, health) behind a table giving the endpoint, certificate and credentials for each of the three ways of getting a server. - docs/getting-started.md: an eleven-line pointer, excluded from the site, kept so links into the repository still land. Removed: manuals/04-quickstart-setup-guide.md, 08-install-linux.md, 09-install-macos.md, local-postgres-setup.md, local-mongodb-setup.md. Reference material moved from the walkthrough to the guide that owns it, text kept, corrected where it disagreed with the binary: - Administration guide: a command index with every manage subcommand (including cache, which no page covered), the assume-role session flags, --endpoint, the console access and audit details, and the runtime settings that were missing (sqlx_log_level, index_propagation_delay_ms, throttling_enabled). ttl_deletion_target_seconds is not a setting the binary accepts and is no longer listed as one. control_plane_delay_seconds seeds at 0.25, not 5; throttling is off by default, not on. - Deployment guide: the connection pool formula with both out-of-pool sessions, the worked example, contention characteristics. - Developer and test guide: external suite registration, runners and options; local databases for the test suite (connection details, pg_hba, config mapping, MongoDB differences). Upgrade manual (#495): a container section measured on the published images. Docker Compose from extenddb-postgres 0.1.10 (catalog 0.0.2) to 0.1.14 (catalog 0.0.3): the bootstrap service runs migrate with the server stopped, the table and item written before the upgrade read back unchanged, and a downgrade leaves the catalog alone while the older server refuses to start and restarts under the Compose policy, with the refusal in the server log. The one-off form, the preview form and its exit status on the published image, the MongoDB Compose file, and the development image (no bootstrap, no migrate, container replaced on the same volume) are covered. The migration writing section moves to a new Contributing page, manuals/14-writing-migrations.md. Also updated: README, AGENTS.md, the Docker Hub overview source, the installer scripts' closing line, the PDF manifest, the sample config comment, the storage backends table, the in-repo skill references, and the doc-consistency script's file list. Site: sidebar for the three install paths and First requests, migrations page under Contributing, strict build clean at 67 pages. The doc version guard passes. The first-requests page was then run in page order against a server built from this tree, which found that its transaction example conditioned on an item the Items section had deleted, so TransactWriteItems was cancelled when followed as written. Batches now precede Query and scan, and the query, batch get, condition check and transactional read use the items the batch writes. The shard iterator example carried a literal shard id the CLI rejects before sending; it is a placeholder now. boto3 is named before the first Python block. The development image and home page start the container with --name extenddb so the Getting started teardown finds it, and the development image page points at First requests. The Getting started pages use one spelling convention, the one the rest of the repository uses. Found and filed separately: extenddb destroy has no Cassandra credential inputs, so it cannot tear down a password-authenticated Cassandra deployment.
LeeroyHannigan
force-pushed
the
feat/docs-site
branch
from
October 31, 2026 14:47
eb8e221 to
34bea38
Compare
LeeroyHannigan
force-pushed
the
feat/docs-install-pages
branch
from
October 31, 2026 14:47
c911384 to
560b5bf
Compare
LeeroyHannigan
added a commit
that referenced
this pull request
Oct 31, 2026
… 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 reads the default account's ID with extenddb manage list-accounts, creates an IAM user, attaches a policy that allows DynamoDB, creates an access key, and exports the key before the request. init prints the admin password but not the account ID. 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 storage design status line said PostgreSQL is the only supported backend. It now names the four backends in crates/: PostgreSQL, SQLite, MongoDB and Cassandra. #412 made the same correction to the README crate list and the architecture guide overview. 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. The Linux and macOS install manuals and the MongoDB setup page also run list-tables before any access key exists. #523 removes those pages. Refs #663
5 of 8 tasks
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.
Closes #492, closes #495. Based on #491 (the documentation site); retargets to
mainwhen that merges.What changes
The Install section had six pages that each cloned, built, initialized and started a server from source, with the platform packages, the TLS steps and the AWS CLI setup repeated on each, plus a 1,461-line walkthrough carrying the manage command reference, runtime settings and tuning beside the install steps. They are replaced by one page per path and one page of first requests:
docs/install-from-source.md: prerequisites, database install per platform, build per backend, init per backend, verify, serve, smoke test, upgrade aftergit pull, tear down, troubleshooting. Two steps the old pages had wrong: MongoDBinitreads the connection string from a seedextenddb.tomland needs--overwrite; Cassandrainitfails under the image's defaultAllowAllAuthenticator.docs/first-requests.md: tables, items, batches, query and scan, transactions, streams and health from the AWS CLI, behind a table giving the endpoint, certificate and credentials for each of the three ways of getting a server.docs/getting-started.mdbecomes an eleven-line pointer, off the site, so links into the repository still land.manuals/04-quickstart-setup-guide.md,08-install-linux.md,09-install-macos.md,local-postgres-setup.md,local-mongodb-setup.md.Reference material from the walkthrough moved to the guide that owns it, corrected where it disagreed with the binary: the administration guide gains a command index with every
managesubcommand, the assume-role flags,--endpoint, console access and audit, and three runtime settings that were missing;ttl_deletion_target_secondsis not a setting the binary accepts and is no longer listed;control_plane_delay_secondsseeds at 0.25, not 5; throttling is off by default, not on. The deployment guide gains the connection pool formula and worked example; the developer guide gains the external suite runners and the local database setup for the test suite.Upgrade manual (#495): a container section measured on the published images. Docker Compose from
extenddb-postgres0.1.10 (catalog 0.0.2) to 0.1.14 (catalog 0.0.3): the bootstrap service runsmigratewith the server stopped, the table and item written before the upgrade read back unchanged, and a downgrade leaves the catalog alone while the older server refuses to start and restarts under the Compose policy. The one-off form, the preview form and its exit status on the published image, the MongoDB Compose file and the development image are covered. Migration writing moves to a new Contributing page,manuals/14-writing-migrations.md.Also updated: README, AGENTS.md, the Docker Hub overview source, the installer scripts, the PDF manifest, the sample config comment, the storage backends table, the in-repo skill references, the doc-consistency script's file list, and the site sidebar.
How it was checked
Every command on the development image, Docker Compose, from-source (PostgreSQL) and first-requests pages was run in order against containers and a binary built from this tree; the quoted output on the pages is from those runs. The MongoDB and Cassandra init sections were run against containers when the page was written. Running first-requests in page order found that its transaction example conditioned on an item the Items section had already deleted, so
TransactWriteItemswas cancelled; the sections are reordered and every block now succeeds in sequence. The shard iterator example carried a literal shard id the CLI rejects client-side; it is a placeholder.Three reader walks (a backend engineer wanting a server, a platform engineer with PostgreSQL already running, and a cover-to-cover read) completed in one to three clicks each. The rendered site: 66 pages, 5,261 links and every fragment resolved, no removed page in search, no horizontal scroll or clipped code block at 390 or 1280 px in either theme. Strict site build clean at 67 pages; the doc version guard passes.
Two pages this change grows were already over the 600-line mark (admin guide 967 to 1,230; upgrade manual 649 to 734) and are left whole.
Filed separately
extenddb destroyhas no Cassandra credential inputs, so it cannot tear down a password-authenticated Cassandra deployment.control_plane_delay_seconds, duplicate headings in the admin and architecture guides, the usage guide's literal shard id, an em dash in themanage create-userwarning).Rebase on main
Rebased with #491 onto
mainat1d0d8f4a2. These changes onmaintouch the pages this PR rewrites, and each is kept:PasswordAuthenticator, then gives the[storage.cassandra]sectioninitwrites, the override flags and how to raise the replication factor. The README keeps its list of storage backend prerequisites, with PostgreSQL and MongoDB pointing at Install from source, and AGENTS.md keeps its Cassandra prerequisite, its Cassandrainitlines and the Cassandra rows of its documentation table.control_plane_delay_secondsrow, and troubleshooting keeps its table lock step and the section on data tables without a catalog row.settings listandsettings getmasking secret values, ahead of this PR's runtime setting subsections.127.0.0.1:27017, the change fix(devtools): publish test databases on loopback only #499 made to the local MongoDB page this PR removes.The deployment guide's two links into the removed MongoDB page, and its pointer to the SQLite section of the getting-started guide, now point at Install from source. With the text from
main, the administration guide grows from 988 to 1,251 lines and the upgrade manual from 681 to 768.Corrections to this PR's own text:
127.0.0.1:9042only.--cassandra-userand--cassandra-passbullet agrees with the example above it: the password can come fromEXTENDDB_CASSANDRA_PASSWORD, and without--cassandra-user,initconnects as$USER, or ascassandrawhenUSERis not set.initline passes the password, the contact point and the superuser as Install from source does, and its list of whatinitcreates names the Cassandra catalog keyspace and the default account's keyspace.At the rebased head,
npm run typecheckand the strictnpm run buildpass with no broken links or anchors.CI passed all 24 checks on
560b5bfda.Publish to GitHub Pagesis skipped, because it runs only when the event is not a pull request.