docserver/about.md

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 conversion tools.

Features

• Documentation for publishing or local build with original Rust mdbook fixed for absolute links and officially reported.
• Rust web server for mdbooks 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 delivered close to code docs (the one generated with Cargo doc for Rust or doxygen for other programming languages).
• It should use markdown 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 and doxygen 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 or apache http server.

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 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 for absolute links and officially reported. We add mdBook Tera preprocessor 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 standard webserver, 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, even reuse and share respositories files.
• Fast prototype with global content and templates.
• 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 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.
• 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 resources pool for Sessions, Users, Permisions and Pages persistence. As content is static, pages can be updated on the fly with no 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 modified version to support multi-books
• mdBook Tera preprocessor to replace urlbase prefix

For server

Main elements / dependencies

• Rust programming language with Tokio and Axum as web application framework for his ergonomics and modularity.
• clap as command line argument parser for main settings and options.
• serde to load config settings into data structs.
• tracing application level tracing.
• tera templating engine to customize web server responses in case like login access, etc.
• casbin as authorization library to define policies and access to resources.
• PASETO Platform-Agnostic SEcurity TOkens used via own small developed library pasetoken with customized private and public keys.

Users credentials and access

• sqlx for user and access store to support several SQL database engines.
• argon2 for password hashing.
• zxcvbn for password strength control.
• totp-rs for 2FA authentication tokens per TOTP.
• openidconnet for OpenID connections.
• lettre A mailer library to send credentials to user.

Sessions handling

• tower to handle cookies in web sever resquests and responses.
• rand - chacha for random generators for encryption keys.
• 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.