search

logto-io / logto

🧑‍🚀 The better identity infrastructure for developers and the open-source alternative to Auth0.
https://logto.io
Mozilla Public License 2.0
8.94k stars 446 forks source link

feature request: Improve Documentation Structure: Consolidate Installation, Deployment, and Upgrade Guides #6805

Open Loongphy opened 1 week ago

Loongphy commented 1 week ago

What problem did you meet?

Description

While attempting to upgrade Logto to a newer version, I encountered difficulties in locating comprehensive deployment and update documentation. The current documentation structure has installation, deployment, and upgrade guides scattered across different sections, making it challenging to find related information efficiently. Even with the search functionality, the experience was cumbersome and time-consuming.

Describe what you'd like Logto to have

Suggested Improvements

  1. Consolidate all deployment-related documentation under a single section
  2. Create a clear hierarchical structure:
    • Getting Started
      • Installation Guide
      • Deployment Options
      • Upgrade Process
      • Migration Guide
  3. Add cross-references between related sections
  4. Include a quick navigation sidebar for deployment-related topics

Example Reference

TimescaleDB's documentation provides a good reference for organized documentation structure, with clear separation and logical grouping of related topics.

https://docs.timescale.com/self-hosted/latest/install/ image

Loongphy commented 1 week ago

I'd be happy to help, but I lack experience in document building.

michaelgiraldo commented 1 week ago

We hear you, we have new docs planned for release by end of the year.

Loongphy commented 1 week ago

upgrade failed: error Found undeployed database alterations, you must deploy them first by npm run alteration deploy command.

  1. Before upgraded, install CLI in the current instance 
    npm install -g @logto/cli
  2. Run database migrations

link https://docs.logto.io/docs/references/using-cli/database-alteration/#determine-the-version-to-deploy

logto db alt deploy <your-version>
  1. Stop the current instance, start the desired version instance

ref: https://github.com/logto-io/logto/issues/6535#issuecomment-2365364498