[docs] Document Linux dev certificate trust improvements - #1446
Conversation
Document the aspire doctor OpenSSL development certificate cache checks and the Linux system trust preservation for Append-mode certificate trust, introduced in microsoft/aspire#18851. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 32c349b4-907d-42e9-aad8-2f0edc267779
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
Validated against microsoft/aspire#18851. The doctor guidance and Linux Append-mode trust behavior now accurately distinguish the AppHost process environment from per-resource environment settings.
There was a problem hiding this comment.
Pull request overview
This PR updates aspire.dev documentation to cover Linux development certificate trust improvements introduced in microsoft/aspire#18851, specifically new aspire doctor OpenSSL cache diagnostics and how Append-mode certificate trust preserves system OpenSSL roots via SSL_CERT_DIR.
Changes:
- Added Linux-specific notes and an example warning output for OpenSSL dev-certs cache issues in
aspire doctor. - Added a Linux Append-mode note explaining how system trust roots are preserved for executable resources via
SSL_CERT_DIR.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx | Documents new Linux OpenSSL dev certificate cache checks and shows a sample warning/fix output. |
| src/frontend/src/content/docs/app-host/certificate-configuration.mdx | Documents Linux SSL_CERT_DIR behavior for Append-mode trust to preserve system roots. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Environment | ||
| ✅ Operating system: Linux Ubuntu 24.04 | ||
| ⚠️ OpenSSL HTTPS development certificate cache is missing the current certificate | ||
| Run 'aspire certs clean' and then 'aspire certs trust' to remove stale or corrupt certificates and regenerate trusted development certificates. |
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
Documents changes from microsoft/aspire#18851
@danegstaTargeting
release/13.5based on the source PR milestone13.5(exact match).Why this is needed
PR 18851 improves Linux dev certificate trust handling in two user-facing ways:
aspire doctornow detects stale, missing, or corrupt OpenSSL development certificate cache entries under the dev-certs trust directory (missing current certificate, missing subject-hash link, or unreadable cache files) and recommendsaspire certs cleanfollowed byaspire certs trust. New resource strings back these checks (e.g.DevCertsOpenSslCacheMissingCurrentCertificateMessage,DevCertsOpenSslCacheMissingHashLinkMessage,DevCertsOpenSslCacheUnreadableMessage,DevCertsInstallOpenSslCleanAndTrustFixFormat).SSL_CERT_DIRwhen set, or materializes well-known system certificate directories when unset, so workloads launched viadotnet runor an IDE (bypassingaspire run's ownSSL_CERT_DIRsetup) don't lose outbound HTTPS trust.Neither behavior was previously documented on aspire.dev.
What changed
reference/cli/commands/aspire-doctor.mdx: Added a note describing the new OpenSSL certificate cache checks and a sample warning/fix-suggestion output block.app-host/certificate-configuration.mdx: Added a note under Append mode explaining the Linux system trust preservation behavior forSSL_CERT_DIR.Both are updates to existing pages; no new pages were created.