Skip to content

docs: one install page per path, first requests page, container upgrades - #523

Open
LeeroyHannigan wants to merge 3 commits into
feat/docs-sitefrom
feat/docs-install-pages
Open

LeeroyHannigan wants to merge 3 commits into
feat/docs-sitefrom
feat/docs-install-pages

Conversation

@LeeroyHannigan

@LeeroyHannigan LeeroyHannigan commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #492, closes #495. Based on #491 (the documentation site); retargets to main when 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 after git pull, tear down, troubleshooting. Two steps the old pages had wrong: MongoDB init reads the connection string from a seed extenddb.toml and needs --overwrite; Cassandra init fails under the image's default AllowAllAuthenticator.
  • 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.md becomes an eleven-line pointer, off the site, 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 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 manage subcommand, the assume-role flags, --endpoint, console access and audit, and three runtime settings that were missing; ttl_deletion_target_seconds is not a setting the binary accepts and is no longer listed; control_plane_delay_seconds seeds 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-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. 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 TransactWriteItems was 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 destroy cannot take Cassandra credentials #500: extenddb destroy has no Cassandra credential inputs, so it cannot tear down a password-authenticated Cassandra deployment.
  • Pre-existing items found on pages this change does not touch are filed as issues (differences page default for control_plane_delay_seconds, duplicate headings in the admin and architecture guides, the usage guide's literal shard id, an em dash in the manage create-user warning).

Rebase on main

Rebased with #491 onto main at 1d0d8f4a2. These changes on main touch the pages this PR rewrites, and each is kept:

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:

  • The Cassandra container on Install from source publishes on 127.0.0.1:9042 only.
  • The --cassandra-user and --cassandra-pass bullet agrees with the example above it: the password can come from EXTENDDB_CASSANDRA_PASSWORD, and without --cassandra-user, init connects as $USER, or as cassandra when USER is not set.
  • AGENTS.md's Cassandra init line passes the password, the contact point and the superuser as Install from source does, and its list of what init creates names the Cassandra catalog keyspace and the default account's keyspace.

At the rebased head, npm run typecheck and the strict npm run build pass with no broken links or anchors.

CI passed all 24 checks on 560b5bfda. Publish to GitHub Pages is skipped, because it runs only when the event is not a pull request.

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
LeeroyHannigan force-pushed the feat/docs-install-pages branch from c911384 to 560b5bf Compare October 31, 2026 14:47
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
@LeeroyHannigan LeeroyHannigan removed their assignment Nov 2, 2026
@navareamol navareamol added this to the 1.0 milestone Nov 3, 2026
docs/getting-started.md: feat/docs-site updated the verify output, the
serve banner, the version output, the console dashboard line and the
auth cache rows of the walkthrough for the migration ledger. This
branch replaces the page with a pointer list. The merged page is the
pointer list; the verify output, serve banner and version output move
to docs/install-from-source.md, and the console and auth cache changes
are already in docs/manuals/05-admin-guide.md on feat/docs-site.

docs/manuals/04-quickstart-setup-guide.md, 08-install-linux.md,
09-install-macos.md: feat/docs-site updated their verify and version
output and the catalog troubleshooting row for the migration ledger.
This branch removes the three pages. The merge keeps the removals and
carries each change into docs/install-from-source.md: the version line
reads catalog migration 5, the verify output has the catalog migrations
check, the serve banner names migration 5, the upgrade section and the
troubleshooting row describe serve exiting 3 on pending migrations and
run migrate without --pg-user, as the general upgrade procedure does.

docs/manuals/07-upgrade-manual.md: feat/docs-site rewrote the manual
for the migration ledger, moved migration writing to CONTRIBUTING.md
and added a sentence on SQLite and MongoDB after step 6. This branch
pointed at a new page, docs/manuals/14-writing-migrations.md, and added
the container upgrade section after step 6. The merged manual keeps the
Writing a New Migration section of feat/docs-site, the SQLite and
MongoDB sentence, and then the container section. In that section the
link to The Catalog Version now points at The Catalog Status, the
pointer to the exit status table names that section, and the sentence
on what is not yet in a published tag names migrations 1 to 5. The
14-writing-migrations.md page described the SQL file and
CATALOG_VERSION mechanism that feat/docs-site replaced, so it is
dropped with its sidebar entry and its docs/build-docs.py entry.

docs/manuals/11-deployment-guide.md: feat/docs-site added the Cassandra
Connection Pool section; this branch added Contention Characteristics
and Auth/authz Caching at the same place. The merged guide has all
three, this branch's two sections first.

docs/troubleshooting.md: feat/docs-site rewrote the fix for an
uninitialized catalog; this branch pointed its link at Install from
source. The merged fix has the new wording with the new link.
docs/getting-started.md: the base updated the walkthrough for catalog
migration 6, the console's metrics dashboard and the end of a session
on a password change or a user deletion. This branch replaces the page
with a pointer list. The merge keeps the pointer list. The migration
number is carried into docs/install-from-source.md, in the version
output, the catalog note, the verify output and the serve banner. The
console changes are in the administration guide, where the base made
the same edits. The connection footprint paragraph and its example are
carried into the deployment guide, which holds that text on this
branch: the footprint adds the max_concurrent_jobs term, the defaults
need 64 of PostgreSQL's 100 connections and the example opens 154.

docs/manuals/04-quickstart-setup-guide.md,
docs/manuals/08-install-linux.md, docs/manuals/09-install-macos.md: the
base changed the verify and version output to migration 6. This branch
removes the three pages in favour of docs/install-from-source.md, which
now shows migration 6. The deletions stand.

docs/manuals/05-admin-guide.md: the base extended the console sessions
sentence with the end of a session on a password change or a user
deletion. This branch added the paragraph on what admin and IAM users
may do in the console and changed the sentence to "end a session". The
merge keeps the paragraph and the base's sentence with this branch's
wording.

docs/manuals/11-deployment-guide.md: the base rewrote the backup and
restore admission paragraph around the max_concurrent_jobs setting.
This branch replaced the one-line pool sizing note with the connection
footprint paragraphs moved from the walkthrough. The merge keeps this
branch's paragraphs, updated as above, and the base's admission
paragraph.

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

v1 Needed for the 1.0 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants