jesus/docserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: fix content
Some checks are pending
Install / Cargo install on ubuntu-latest (push) Waiting to run
Details

Browse Source
This commit is contained in:
Jesús Pérez 2024-10-01 16:26:18 +01:00
parent 445f43d848
commit 422996208c
No known key found for this signature in database
1 changed files with 12 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
about.md
View File

@ -24,7 +24,7 @@ One server instance for all Documentations in contexts/use-cases with sessions,
- To build a documentation service for a development or service
- It should include diagrams, data-flow, explanations about choices, etc.
- It should be delivery close to code docs (the one generated with [Cargo doc](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for **Rust** or [doxygen](https://www.doxygen.nl/) for other programming languages).
- It should be delivered close to code docs (the one generated with [Cargo doc](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for **Rust** or [doxygen](https://www.doxygen.nl/) for other programming languages).
- It should use [markdown](https://www.markdownguide.org/) mainly to reuse software repositories description files, but also includes **HTML** content.
- Publishing result will be a static web service with pages in **HTML, CSS, JS**.
@ -39,7 +39,7 @@ As target projects in 2022 were in Rust with some bindings to C, we thought [mdb
- Someone had a bright idea / requirement to have documentation translated to a second language.
- We do not want to end up deploying several webservers for each case with a complicate pipelines to handle and too much resources to serve in public or locally.
For the **Rust** part we thought that with [mdbook](https://rust-lang.github.io/mdBook/) we were able to generate static contents under one web server instance and reduce problem to pages ayout, links, some kind of includes for global elements and use some templates.
For the **Rust** part we thought that with [mdbook](https://rust-lang.github.io/mdBook/) we were able to generate static contents under one web server instance and reduce problem to pages layout, links, some kind of includes for global elements and use some templates.
That was not true, we had to [Fix Rust mdbook](https://repo.jesusperez.pro/jesus/mdbook) for absolute links and officially reported.
We add [mdBook Tera preprocessor](https://github.com/avitex/mdbook-tera) to replace **urlbase prefix** defined in settings and create scripts to take care of **paths, book.toml, index.hbs, etc** in building final content.
@ -51,8 +51,8 @@ We add [mdBook Tera preprocessor](https://github.com/avitex/mdbook-tera) to repl
- We need a kind or persistence mechanism to handle sessions request form users so we can verify ids and permissions.
- As we were under security restrictions we needed strong guaranties of access and control, shomething to be used, implemented and manage in a local provision or in a public service use case.
First options to use <i>standard webserver</i> even via plugins and extensions.
Finally we end up with our **DocServer** development to cover all requirements so far in an extensible and customized way so we can adjust and secure to what ever was required with several options to handle sessions, users and persissions persistence and full procedures to user login and credentials.
First options to use <i>standard webserver</i>, even via plugins and extensions.<br>
Finally we end up with our **DocServer** development to cover all requirements so far in an extensible and customized way, so we can adjust and secure to what ever was required with several options to handle sessions, users and persissions persistence and full procedures to user login and credentials.
## DocServer Scenarios
@ -62,13 +62,13 @@ There are several **Final Service** perspective or use cases.
- Easy share or write documentation, notes, diagrams, etc. with or without [markdown](https://www.markdownguide.org/), even reuse and share respositories files.
- Fast prototype with global content and templates.
- They know who is allowed to read or to include others on the fly.
- They know who is allowed to read docs or to include others on the fly.
- Tailor content to sync with code, features, branches, etc.
- They can review final result before to open access to others.
> With customized CD/CI pipelines they ideally only need to push content to a doc repository and all the rest should be automated.
### For Services
### For Service
- A single server deployment with access to persistence storage for Users, Sessions and Permisions.
- Settings are declared in several files to easy access and changes.
@ -86,9 +86,9 @@ There are several **Final Service** perspective or use cases.
### For Users
They can have a customize document access experience with personal links, etc.
They can have their own profile and credentials.
We can refer to their specific and customized docs with defined acces via roles or groups.
- They can have a customize document access experience with personal links, etc.
- They can have their own profile and credentials.
- We can refer to their specific and customized docs with defined acces via roles or groups.
## Technical choices: What is in ?
@ -105,8 +105,8 @@ We can refer to their specific and customized docs with defined acces via roles
- [clap](https://github.com/clap-rs/clap) as command line argument parser for main settings and options.
- [serde](https://serde.rs/) to load config settings into **data structs**.
- [tracing](https://github.com/tokio-rs/tracing) application level tracing.
- [Tera](https://keats.github.io/tera/) templating engine to customize web server responses in case like login access, etc.
- [Casbin](https://casbin.org/) as authorization library to define policies and access to resources.
- [tera](https://keats.github.io/tera/) templating engine to customize web server responses in case like login access, etc.
- [casbin](https://casbin.org/) as authorization library to define policies and access to resources.
- [PASETO](https://paseto.io) Platform-Agnostic SEcurity TOkens used via own small developed library **pasetoken** with customized private and public keys.
#### Users credentials and access
@ -123,4 +123,4 @@ We can refer to their specific and customized docs with defined acces via roles
- [tower](https://github.com/tower-rs/tower) to handle cookies in web sever resquests and responses.
- [rand - chacha](https://github.com/rust-random/rand) for random generators for encryption keys.
- [sqlx](https://github.com/launchbadge/sqlx) option backend for sessions in async mode.
- A **FileStore** option has been developed as alternative for session persistence belong to by default **memStore** with no disk pesistence.
- A **FileStore** option has been developed as alternative for session persistence belong to by default **memStore** with no disk pesistence.