Skip to content

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

Open
LeeroyHannigan wants to merge 1 commit into
feat/docs-sitefrom
feat/docs-install-pages
Open

LeeroyHannigan wants to merge 1 commit 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

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.

1 participant