Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: restructure, clarify, consolidate existing docs #1726

Open
wants to merge 42 commits into
base: main
Choose a base branch
from

Conversation

desimone
Copy link
Collaborator

@desimone desimone commented Dec 29, 2024

Summary
This PR reorganizes our documentation to unify repetitive content (e.g., multiple versions of identity/JWT verification, CLI usage, and certificate guides) into a more readable structure. We want newcomers to see a clear “start here” path, discover high-level product capabilities, and then explore advanced references once they’re ready for production. No changes have been made to our existing reference docs or guides.

Improved Onboarding Flow

  • Fundamentals A step-by-step tutorial for new users (Quickstart, policy building, SSO, advanced routes).
  • Capabilities High-level feature topics (authorization, routing, branding, etc.) that highlight Pomerium’s value proposition and show how each feature solves user problems.
  • Internals Advanced deep-dives (architecture, zero trust, connection details) for production or experienced users wanting best practices and deeper context.

Consolidated Overlapping Docs (many others)

  • Identity & JWT Verification Merged scattered pages (old “JWT Verification,” separate identity provider docs) into a single “Getting Users’ Identity” doc.
  • CLI/Desktop Unified multiple how-to guides for TCP/UDP tunneling into a single “Clients for TCP & UDP” doc, clarifying both CLI and Desktop usage.
  • Certificates Streamlined references on certificate usage and mTLS (previously found in separate guides) into one “Certificates & TLS” doc.

Docs Platform Improvements

  • Removed some older version references from the sidebar dropdown.
  • Fixed syntax highlighting issues.
  • Fixed a hack (e.g., a custom webpack plugin snippet) in docusaurus.config.js for future use.

Follow-Up Work

  • Ensure all old links have proper redirects (hell)
  • Update the overview page’s flow diagram; using a mermaid placeholder for now
  • Further unify concepts and glossary items
  • On the “Get Started” page, add tabbed instructions for both Core and Zero so users drop into the correct fundamentals
  • Consider reorganizing reference docs for better navigation
  • Fix Algolia’s search results (the new consolidation should help)
  • Move the JIT access doc into the PPL section and expand PPL coverage
  • Overhaul the “Deployment” section for clarity—guide GCP or K8s Ingress use cases, unify Kubernetes docs more effectively
  • Decide whether to keep or update the old “High Availability” doc (merged with “config”)
  • Add Autocert details to the automatic domain registration doc
  • Reference Envoy usage in “Proxying & Routing” docs
  • Update enterprise callouts to mention Zero; replace hard-coded boxes with admonition blocks
  • quickstart: can't click finish before copying docker config #1727

Request for Review

  • Ensure we haven’t lost key details while merging identity/JWT, CLI, and certificate (and many others!)
  • Confirm the fundamentals → capabilities → internals progression makes sense.
  • Let me know if additional references or cross-links would be helpful.

…ity providers

- Corrected links in existing documentation to point to the updated paths.
- Removed the identity providers category file as it is no longer needed.
- Added new integration guides for Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, OIDC, Okta, OneLogin, and Ping.
- Included images and examples for each integration to enhance clarity and usability.
- Updated the quick start references across multiple guides to reflect the new structure.

This commit enhances the onboarding experience for users integrating with various identity providers and ensures all links are current.
…rprise guides

- Corrected links across multiple documentation files to point to the updated '/deploy/enterprise' paths.
- Added new guides for Pomerium Enterprise, including installation, configuration, and metrics.
- Introduced new images and examples to enhance clarity in the documentation.
- Created new files for managing clusters, JWT verification, and mutual authentication.
- Removed outdated references and ensured all links are current for a better user experience.

This commit improves the onboarding process for users and ensures that all documentation is aligned with the latest deployment structure.
…ines

- Consolidated the 'Community' category in the sidebar to streamline navigation, commenting out the section for future reference.
- Enhanced the 'What is Pomerium?' documentation by expanding the description and adding key benefits and operational details.
- Removed the 'Code of Conduct' and 'Contributing' documents to simplify the community section, as they are no longer needed.
- Deleted associated images that were part of the removed documents.

This commit improves the clarity and accessibility of the documentation while ensuring that outdated content is removed for a better user experience.
- Consolidated and commented out the 'Pomerium Zero' and 'Pomerium Core' categories in the sidebar for future reference, while introducing a new 'Deploy' category to streamline navigation.
- Updated image paths in the recovery token documentation for better organization.
- Removed the outdated 'Community' documentation and added new guides for Pomerium Enterprise, including installation, configuration, and troubleshooting.
- Introduced new integration guides for external data sources and enhanced existing documentation with additional examples and images.
- Added troubleshooting information for common configuration issues and clarified the process for generating recovery tokens.

This commit improves the clarity, accessibility, and usability of the documentation, ensuring users have the most up-to-date information for deploying and managing Pomerium.
- Changed all instances of the Pomerium Docker image from specific version tags (v0.27.2 and v0.28.0) to the 'latest' tag across multiple documentation files.
- This update ensures users are directed to use the most current version of Pomerium for deployment, enhancing the overall user experience and reducing potential issues with outdated images.

This commit improves the clarity and usability of the documentation by promoting the use of the latest available resources.
- Commented out the 'Kubernetes' category in the sidebar for future reference while introducing a new 'Deploy' category to improve navigation.
- Updated image paths in the device identity documentation for better organization.
- Added new files for Kubernetes configuration, including global settings, ingress setup, and quickstart guides.
- Introduced new images to enhance clarity and usability in the documentation.
- Removed outdated images and files related to previous versions and community guidelines.

This commit improves the clarity, accessibility, and usability of the documentation, ensuring users have the most up-to-date information for deploying and managing Pomerium in Kubernetes environments.
… security policy page

- Deleted the standalone 'cryptography.md' file to streamline documentation.
- Integrated essential cryptography details into the 'security.md' file, enhancing the security policy with comprehensive information on encryption in transit and at rest.
- Updated the title and keywords of the security policy to reflect the inclusion of cryptography topics.

This commit improves the organization and accessibility of security-related information, ensuring users have a consolidated resource for understanding Pomerium's security measures.
- Updated the 'certificates.mdx' file to change references for zero trust principles from the concepts section to the internals section.
- Deleted the 'cluster-status.mdx' file, consolidating its content into the 'clusters.mdx' file, which now includes a comprehensive troubleshooting section for cluster status alerts.
- Enhanced the 'clusters.mdx' file with detailed explanations of various cluster status alerts, their causes, and resolution steps.

This commit improves the organization and accessibility of cluster management documentation, ensuring users have a consolidated resource for troubleshooting cluster health issues.
…ication services

- Removed the 'Hosted Authenticate Service' documentation and integrated its content into the 'Authentication' section, streamlining the information for users.
- Added new documentation for non-HTTP protocols, including TCP and UDP, detailing how to tunnel these connections through Pomerium.
- Created examples for various services (e.g., Redis, MySQL, PostgreSQL, RDP, and SSH) to demonstrate how to establish secure connections using Pomerium's CLI and Desktop clients.
- Introduced a new 'Custom Domains' guide for Pomerium Zero, explaining how to set up and manage custom domains effectively.
- Updated existing documentation to reflect the latest changes and improve clarity, ensuring users have access to comprehensive and organized resources.

This commit enhances the usability and accessibility of the documentation, providing users with clear guidance on utilizing Pomerium for non-HTTP services and authentication management.
- Consolidated and updated sidebar entries for capabilities, including renaming and reorganizing sections for clarity.
- Introduced new documentation for 'Certificates and TLS' and 'Self-Remediation', enhancing user guidance on these features.
- Removed outdated files related to 'Device Identity', 'Load Balancing', and 'Single Sign-out', streamlining the documentation.
- Updated existing files to reflect new titles and keywords, improving searchability and relevance.
- Enhanced routing documentation to clarify proxying and load balancing methods, ensuring users have comprehensive resources.

This commit improves the organization, clarity, and usability of the documentation, providing users with up-to-date and accessible information on Pomerium's capabilities.
… identity management

- Updated sidebar entries for improved organization and clarity, including the addition of new categories for 'Self-Managed (Core)' and 'Cloud Managed (Zero)'.
- Introduced new documentation files covering advanced policies, routes, and user identity verification, enhancing user guidance on these features.
- Removed outdated files related to 'Getting Users Identity' and 'JWT Verification', streamlining the documentation.
- Updated existing files to reflect new titles and keywords, improving searchability and relevance.
- Added new images and examples to clarify complex concepts and processes.

This commit improves the structure, clarity, and usability of the documentation, providing users with up-to-date and accessible information on Pomerium's capabilities and identity management features.
…erences and Docker image paths

- Updated links to the Self-Hosted Authenticate Service across multiple files to point to the new authentication documentation.
- Changed all instances of the Pomerium Docker image from 'cr.pomerium.com' to 'pomerium.com' for consistency and clarity.
- Enhanced various documentation sections to improve user guidance on authentication and deployment processes.

This commit improves the accuracy and usability of the documentation, ensuring users have access to the latest information regarding Pomerium's authentication services and deployment practices.
- Introduced new documentation files for Pomerium Core, detailing installation methods, configuration, and running the server using pre-built binaries, Docker images, or building from source.
- Added an extensive upgrading guide for both Pomerium Core and Enterprise, outlining breaking changes, deprecations, and important notes for each version.
- Removed outdated files related to Pomerium Zero and consolidated relevant content into the new structure, enhancing clarity and usability.
- Updated various sections to improve user guidance on installation, configuration, and upgrade processes.

This commit enhances the documentation's organization and accessibility, ensuring users have up-to-date and comprehensive resources for deploying and managing Pomerium.
…y updates

- Added new features including a feedback widget, improved IdP directory sync performance, and a new "Exists" condition for external data sources.
- Expanded `--disable-validation` into a new `--validation-mode` option with additional modes.
- Fixed several UI issues in the policy builder and restricted access to the debug "DataBroker Browser" page to global admins.
- Included various bug fixes across multiple versions, ensuring a smoother user experience and improved functionality.

This commit provides users with comprehensive information on the latest changes and improvements in the upgrading process for Pomerium.
- Updated the title of the upgrading documentation to 'Upgrading' for brevity.
- Enhanced the description to include 'changelog' for better context on the content provided.
- These changes aim to improve the clarity and accessibility of the upgrading process for both Pomerium Core and Enterprise users.
- Introduced comprehensive documentation on Clusters in Pomerium Zero, detailing architecture, deployment, and management.
- Added new images to illustrate cluster concepts and configurations.
- Updated the upgrading documentation to reflect recent changes, including the removal of deprecated files and integration of relevant content.
- Enhanced troubleshooting sections for cluster status alerts, providing clear resolution steps for common issues.

These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing Pomerium Zero and its clusters.
- Modified the pre-commit configuration to exclude a specific Kubernetes reference file.
- Updated Docusaurus configuration to include a webpack fix for debugging.
- Upgraded Docusaurus dependencies to the latest version.
- Enhanced documentation by adding a new section for custom domains in Pomerium Zero, including detailed instructions and images.
- Revised various documentation links to ensure consistency and accuracy, particularly for Kubernetes deployment references.
- Removed outdated CORS documentation and integrated relevant content into troubleshooting guides.
- Added a comprehensive troubleshooting guide to assist users with common configuration issues.

These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing Pomerium and its deployment processes.
- Commented out the custom plugin for webpack debugging in `docusaurus.config.js` to streamline configuration.
- Upgraded `mermaid` from version 10.9.3 to 11.4.1 and `redocusaurus` from 2.0.2 to 2.2.0 in `package.json` for improved functionality.
- Added `image-size` as a new dependency in `devDependencies` and updated `prettier` to version 3.4.2.
- Removed the `webpackDebugFix.js` file to eliminate redundant code.

These changes enhance the clarity of the configuration and ensure the project uses the latest dependencies for better performance and maintainability.
…ntegrations

- Introduced new documentation files for various identity providers including Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, Okta, OneLogin, and Ping, enhancing user guidance on integration processes.
- Updated sidebar entries for improved organization and clarity, adding new categories for 'User Identity' and 'User Standing'.
- Added comprehensive documentation on device context and request context integrations, detailing their functionalities and configurations.
- Removed outdated files and consolidated relevant content to streamline the documentation.
- Enhanced existing documentation with new images and examples to clarify complex concepts and processes.

These changes improve the structure, clarity, and usability of the documentation, ensuring users have access to up-to-date resources for managing user identity and integrations with Pomerium.
- Removed outdated version links from the Docusaurus configuration to streamline navigation.
- Cleaned up sidebar entries by commenting out deprecated categories and consolidating relevant documentation, enhancing clarity and organization.
- Updated import paths in the configuration documentation for consistency.
- Improved table formatting in service URLs documentation for better readability.

These changes enhance the overall usability and clarity of the documentation, ensuring users have access to the most relevant and organized resources for Pomerium.
- Refactored `docusaurus.config.js` to use updated imports for code themes, enhancing maintainability.
- Upgraded several MUI packages and `prism-react-renderer` in `package.json` to their latest versions for improved functionality and performance.
- Corrected documentation links related to device identity across multiple files, ensuring users are directed to the correct resources.
- Updated redirect paths in `_redirects` to reflect the new documentation structure for device identity.

These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to the most relevant and up-to-date resources for Pomerium.
- Updated the sidebar link for the Integrations category to point to the new documentation structure.
- Added comprehensive new documentation files for integrating external data sources and configuring identity providers, including Keycloak.
- Introduced detailed guides on using external data sources with Pomerium, including supported formats and configuration settings.
- Removed outdated OIDC documentation and consolidated relevant content to streamline user guidance.
- Added images and examples to clarify integration processes and enhance user understanding.

These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing integrations with Pomerium.
- Standardized formatting of titles and descriptions in the Keycloak integration guide.
- Consolidated image display for better visual flow and readability.
- Removed unnecessary blank lines to enhance document cleanliness.
- Updated the caution note formatting for improved emphasis.

These changes improve the overall clarity and usability of the Keycloak integration documentation, ensuring users have a more streamlined experience when configuring Pomerium with Keycloak.
- Removed unnecessary comments and links in the sidebars to streamline navigation.
- Standardized formatting across multiple files, ensuring consistent use of apostrophes and punctuation.
- Enhanced descriptions and titles for better clarity in various guides, including those related to authentication, authorization, and device identity.
- Consolidated and improved the organization of documentation related to Pomerium's capabilities and integrations.

These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Updated sidebar links to correct paths, ensuring accurate navigation to Kubernetes deployment references.
- Standardized formatting across multiple files, including titles and descriptions, for improved readability.
- Enhanced documentation by correcting typos and ensuring consistent terminology, particularly in the context of device identity and Kubernetes configurations.
- Consolidated and improved the organization of documentation related to Pomerium's capabilities and integrations, including the introduction of new sections for WebAuthn device identity.

These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Removed the 'APIs' dropdown from the sidebar in `docusaurus.config.js` to streamline navigation.
- Enhanced the description of Pomerium in `index.mdx` to clarify its functionality, emphasizing the verification of user identity, device state, and request context.
- Improved formatting and clarity in the documentation, ensuring consistent terminology and readability.

These changes enhance the overall usability and clarity of the documentation, providing users with a more coherent resource for understanding Pomerium's capabilities.
- Updated links across multiple files to ensure accurate navigation to identity provider and integration resources.
- Corrected paths for various documentation sections, including device identity and authentication, to reflect the new structure.
- Enhanced descriptions and formatting for improved readability and coherence in guides related to user identity management and integrations.
- Consolidated and organized documentation to streamline user guidance on Pomerium's capabilities and integrations.

These changes improve the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Updated multiple links across various files to ensure accurate navigation to the correct documentation sections, particularly for identity providers and integration resources.
- Corrected paths for guides related to device identity, authentication, and troubleshooting to reflect the new structure.
- Enhanced descriptions and formatting for improved readability and coherence in guides, including those related to user identity management and integrations.
- Consolidated and organized documentation to streamline user guidance on Pomerium's capabilities and integrations.

These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
Copy link

netlify bot commented Dec 29, 2024

Deploy Preview for pomerium-docs ready!

Name Link
🔨 Latest commit 8b099eb
🔍 Latest deploy log https://app.netlify.com/sites/pomerium-docs/deploys/6770f84972096200081fe09f
😎 Deploy Preview https://deploy-preview-1726--pomerium-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

Copy link

netlify bot commented Dec 29, 2024

Deploy Preview for pomerium-docs ready!

Name Link
🔨 Latest commit 54ef1fe
🔍 Latest deploy log https://app.netlify.com/sites/pomerium-docs/deploys/6777073dd6d4bc0008a12b38
😎 Deploy Preview https://deploy-preview-1726--pomerium-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

- Added a comprehensive list of new terms to the cspell configuration, including technical jargon and company-specific terminology.
- This update enhances the spell checker’s ability to recognize relevant terms, improving the overall quality of documentation and code comments.

These changes ensure that the spell checker is aligned with the current terminology used within the project, facilitating better documentation practices.
- Changed the checkout action to use the latest version (v3) for improved stability and performance.
- Updated the pre-commit action to version 3.0.1, ensuring compatibility with the latest features and fixes.

These changes enhance the reliability of the pre-commit workflow, ensuring that the latest updates are utilized for better performance and functionality.
- Upgraded Prettier from version 2.7.1 to 3.4.2 for improved formatting capabilities.
- Updated cspell from version 6.2.0 to 8.17.0 to enhance spell checking accuracy and support for new terms.

These changes ensure that the project utilizes the latest tools for code formatting and spell checking, improving overall code quality and documentation accuracy.
- Updated multiple documentation files to replace references to the old Pomerium CLI and Desktop client links with the new consolidated guide at /docs/deploy/clients.
- Revised links in various sections to ensure accurate navigation for TCP and UDP connections, enhancing user guidance on non-HTTP protocols.
- Removed outdated client documentation files and images, streamlining the resource structure for better accessibility.
- Improved overall clarity and consistency in documentation formatting and terminology.

These changes enhance the usability and coherence of the documentation, providing users with a more organized resource for managing Pomerium's capabilities.
- Updated multiple documentation files to correct paths and improve navigation, including the integration of new recovery token and mkcert installation guides.
- Replaced outdated references to the old Pomerium CLI and Desktop client links with updated paths for better clarity.
- Added new markdown files for generating recovery tokens and installing mkcert, enhancing user guidance.
- Removed obsolete images and files to streamline the documentation structure.

These changes improve the organization and accessibility of the documentation, providing users with clearer guidance on Pomerium's features and setup processes.
@desimone desimone changed the title 💀 docs: restructure, clarify, consolidate existing docs Dec 31, 2024
@desimone desimone marked this pull request as ready for review December 31, 2024 17:37
@desimone desimone requested a review from a team as a code owner December 31, 2024 17:37
@desimone desimone requested review from rjbeers, gaurdro and wrmedford and removed request for a team December 31, 2024 17:37
content/docs/index.mdx Outdated Show resolved Hide resolved
desimone and others added 2 commits January 2, 2025 13:19
- Updated the GitHub Actions pre-commit workflow to use specific commit hashes for the checkout and pre-commit actions, ensuring consistency and stability.
- Revised documentation links in index.mdx and quickstart.mdx to point to the correct paths, improving navigation for users.
- Added a note in configuration.mdx to clarify the configuration options for running Pomerium in different service modes.

These changes enhance the accuracy and usability of the documentation, providing clearer guidance for users and ensuring the pre-commit checks are up-to-date.
@desimone desimone requested review from gaurdro and rjbeers January 2, 2025 21:38
@rjbeers
Copy link
Contributor

rjbeers commented Jan 3, 2025

Generally, I'm a fan. I didn't review every line, but the new structure is an improvement over the current.
I walked through the new user flow. It makes more sense and flows easier in my mind.
https://www.pomerium.com/docs/clients/pomerium-cli is a top visited page, so we may want to fill in a redirect for that sooner rather than later. Maybe we can use google analytics to set the top visited ones.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants