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

chore: add about document
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 14:24:22 +01:00
parent eca6d5efd6
commit 445f43d848
No known key found for this signature in database
1 changed files with 126 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
about.md Normal file
View File

@ -0,0 +1,126 @@
# DocServer
Documentation Services for multiple docs content with access restricions and permissions
One server instance for all Documentations in contexts/use-cases with sessions, users/groups access
> [!IMPORTANT]
> Although it was born to document **Rust** projects, it can be used as a documentation service for projects and services not related to **Rust** environments at all or mixed ones.
> As it provides static content it can also be used with or without [markdown](https://www.markdownguide.org/) conversion tools.
<img src="https://cv.jesusperez.pro/assets/images/projects/docserver-w.png">
## Features
- Documentation for publishing or local build with original [Rust mdbook fixed](https://repo.jesusperez.pro/jesus/mdbook) for absolute links and officially reported.
- <u>Rust web server for mdbooks</u> created with authentication and authorizations (permissions based on roles).
- **Control access** for static content like documentation (books and code) with a lot of options for settings.
- **Documentations access control and info** for users and groups allows separating content for development, distribution or future versions, etc.
- Can run **under one instance server**, can be implemented in a local or public infrastructure with automations CD/CI.
## History behind
### A simple straight forward approach
- 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 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**.
As target projects in 2022 were in Rust with some bindings to C, we thought [mdbook](https://rust-lang.github.io/mdBook/) and [doxygen](https://www.doxygen.nl/) were enough to cover documentation requirements, probably by adding some scripts or tools to generate and glue all together in a pages layout to be served under a standard webserver like [nginx](https://nginx.org/en/) or [apache http server](https://httpd.apache.org/).
### Houston, we have a problem! New requirements coming in town
- We are developing several choices it will end up with serveral products or packages, they will require different documentation, specially for highend customers with customized features and modifications.
- We are working on serveral Development/Service versions and branches, they also require different documentation.
- We need a basic place to write about tools, procedures and rules selected, why, where and how to be applied or changed. Some of them are even specific only for project.
- We have to reuse as much as it is possible in a **multi-document service** just to write them once and only change them in one place.
- 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.
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.
### Security comes to play: Who is allowed to see what ?
- We need to implement **permissions** and **control access** at least to some documentations while keep all under one web-server as a **Central Documentation Service**.
- Autorizations requires a target so we need to define users and groups and associate them to documentation resources.
- 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.
## DocServer Scenarios
There are several **Final Service** perspective or use cases.
### For Developer
- 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.
- 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
- 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.
- Authorizations are defined based on ids, groups or roles and linked to content resouces path (URL endpoints).
- There are several ways to store Sessions and Users.
- User Credentials basic handlings is covered and can be customized in templates subsystem with no code compilation need.
- Credentials requirements can be customize.
- Sessions are encrypted with customized keys.
- Permissions and access policies can be customized on files.
- UI Interface can be translated to other languages.
- TLS certificates and Sessiong tokens can be set for the services.
> With customized CD/CI pipelines they ideally only need change settings and manage (HA,scale,etc) one single pool of resource for Sessions,Users, Permisions and Pages persistence.
> As content is static, pages can be updated on the fly with services interruption via content CD/CI pipelines.
### 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.
## Technical choices: What is in ?
### For content
- Static content generated via [mdbook](https://rust-lang.github.io/mdBook/) modified version to support **multi-books**
- [mdBook Tera preprocessor](https://github.com/avitex/mdbook-tera) to replace **urlbase prefix**
### For server
#### Main elements / dependencies
- Rust programming language with [Tokio](https://tokio.rs/) and [Axum](https://github.com/tokio-rs/axum) as web application framework for his ergonomics and modularity.
- [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.
- [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
- [sqlx](https://github.com/launchbadge/sqlx) for user and access store to support several **SQL** database engines.
- [argon2](https://github.com/RustCrypto/password-hashes/tree/master/argon2) for password hashing.
- [zxcvbn](https://github.com/shssoichiro/zxcvbn-rs) for password strength control.
- [totp-rs](https://github.com/constantoine/totp-rs) for 2FA authentication tokens per TOTP.
- [openidconnet](https://github.com/ramosbugs/openidconnect-rs) for OpenID connections.
- [lettre](https://github.com/lettre/lettre) A mailer library to send credentials to user.
#### Sessions handling
- [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.