Skip to content

docs: document --dapc seed flag for air-gapped OSS installs#1417

Merged
xiaoyijun merged 8 commits into
logto-io:masterfrom
darcyYe:yemq-docs-add-dapc-flag
Jun 1, 2026
Merged

docs: document --dapc seed flag for air-gapped OSS installs#1417
xiaoyijun merged 8 commits into
logto-io:masterfrom
darcyYe:yemq-docs-add-dapc-flag

Conversation

@darcyYe

@darcyYe darcyYe commented May 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Documents the new db seed --disable-admin-pwned-password-check (alias --dapc) flag added to @logto/cli in logto-io/logto#8859. The flag pre-disables the Have I Been Pwned (HIBP) breach check on the admin tenant, unblocking first-admin sign-up for OSS deployments that cannot reach api.pwnedpasswords.com (air-gapped data centers, strict egress firewalls).

Files updated:

  • docs/logto-oss/using-cli/README.mdx — new section "Seed for air-gapped or offline deployments" describing the flag, its scope (admin tenant only), and how to re-enable HIBP later from the Admin Console > Sign-in experience > Password policy.
  • docs/logto-oss/deployment-and-configuration.mdx — short admonition under "Database setup" cross-referencing the new CLI section so air-gapped operators see the flag while planning their Postgres setup.

Only English docs are updated. Translated copies under i18n/ are left to the regular translation pipeline.

Testing

Tested locally

Checklist

  • .changeset (only when explicitly required)
  • unit tests
  • integration tests
  • necessary TSDoc comments

@darcyYe darcyYe marked this pull request as ready for review May 22, 2026 08:17
Copilot AI review requested due to automatic review settings May 22, 2026 08:17

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates Logto OSS documentation to explain the new db seed --dapc / --disable-admin-pwned-password-check flag in @logto/cli, aimed at unblocking first-admin sign-up in air-gapped/offline environments where api.pwnedpasswords.com is unreachable.

Changes:

  • Adds a new “Seed for air-gapped or offline deployments” section to the Logto CLI docs, including usage examples and scope notes (admin tenant only).
  • Adds a cross-referenced tip under “Database setup” in deployment docs to help operators discover the flag during installation planning.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
docs/logto-oss/using-cli/README.mdx Documents --dapc behavior, scope, and provides CLI/npm/npx examples with a stable anchor for cross-linking.
docs/logto-oss/deployment-and-configuration.mdx Adds an “Air-gapped or offline installs” tip that points readers to the detailed CLI documentation section.
Comments suppressed due to low confidence (1)

docs/logto-oss/using-cli/README.mdx:91

  • The service name is typically written as “Have I Been Pwned” (HIBP). Consider updating the link text to match the official name for clarity and consistency.
When set, the seeded `sign_in_experiences.password_policy` row for the **admin tenant** is `{"rejects": {"pwned": false}}` instead of the default `{}`. This skips the [HaveIBeenPwned (HIBP)](https://haveibeenpwned.com/) password breach check during the first admin sign-up, so creating the initial admin from the Welcome page no longer hangs when `api.pwnedpasswords.com` is unreachable (for example in air-gapped data centers or behind strict egress firewalls).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/logto-oss/using-cli/README.mdx Outdated
Comment thread docs/logto-oss/deployment-and-configuration.mdx Outdated
darcyYe and others added 2 commits May 22, 2026 16:40
Air-gapped users can now run a single `logto init --dapc` instead of
`init --skip-seed` + `db seed --dapc`. Updates the install command
options table, the air-gapped CLI section, and the deployment admonition
to surface both code paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@xiaoyijun

xiaoyijun commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Pushed a few follow-up commits to this branch (via maintainerCanModify). Summary of what changed and why:

Correctness

  • Removed the "re-enable from the Admin Console" claim. The flag only seeds the admin tenant's sign-in experience, which is not exposed in the Admin Console (the Console manages the default/other tenants). There is currently no Console path to toggle the HIBP check on the admin tenant, so the old sentence was misleading. We also don't document raw SQL for this, so I just dropped the sentence. (48b0ae362)
  • Dropped the --oc row from the install options table. logto init has no --oc option; official connectors are added separately via logto connector add --official. (48b0ae362)
  • Reworded the alias note. In the current CLI, --dapc is the canonical option key and --disable-admin-pwned-password-check is its alias (these were swapped after this PR was first drafted). Both work as input, so the wording is now neutral ("…are aliases; either one works") instead of calling --dapc the "short alias". (48b0ae362)

Polish

  • Install options → Markdown table. Replaced the hand-aligned bash block with a table; the cross-reference link now lives in the --dapc description cell and renders as a real link (it can't inside a code fence). (fab9c8e18, supersedes 266883778)
  • Removed em-dashes from the new air-gapped section. (b8d483b19)
  • Added an npx tab to "One-step install" so it matches the seed group (CLI/npm/npx). The two npm tabs intentionally differ — npm init @logto@latest for a fresh install vs. npm run cli inside an existing instance. (2ac967557)

Verified locally with docusaurus start: both pages compile and render.

xiaoyijun added 5 commits June 1, 2026 17:25
- Remove the claim that the admin tenant's HIBP check can be re-enabled
  from the Admin Console; the admin tenant's sign-in experience is not
  exposed there.
- Describe --dapc and --disable-admin-pwned-password-check as plain
  aliases of each other instead of implying one is canonical.
- Drop the non-existent --oc option from the install options table.
Links inside a fenced code block render as literal text, so the cross-reference
was not clickable. Move it into the prose below the block, matching the pattern
used in manage-database-configs.mdx.
Replace the manually aligned code block with a Markdown table so the columns
stay readable and the air-gapped cross-reference link renders as a real link
inside the description cell.
@xiaoyijun xiaoyijun force-pushed the yemq-docs-add-dapc-flag branch from 3e0db13 to 2ac9675 Compare June 1, 2026 09:26
@xiaoyijun xiaoyijun merged commit b9e124f into logto-io:master Jun 1, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

4 participants