Merge pull request #3259 from esl/doc-structure-rework

Restructure the documentation

README.md

@@ -13,11 +13,11 @@
 * Documentation: [https://esl.github.io/MongooseDocs/](https://esl.github.io/MongooseDocs/)
 
 ## Get to know MongooseIM
-MongooseIM is a robust and efficient chat (or instant messaging) platform aimed at large installations.
+MongooseIM is a robust, scalable and efficient XMPP server at the core of an Instant Messaging platform aimed at large installations.
 
 <img align="left" src="doc/MongooseIM_logo.png" alt="MongooseIM platform's logo"/>
 
-Designed for enterprise, it is fault-tolerant, can utilise the resources of multiple clustered machines, and easily scales for more capacity by simply adding a box or VM.
+Designed for enterprise, it is fault-tolerant, can utilise the resources of multiple clustered machines, and easily scales for more capacity by simply adding a box or a VM.
 
 MongooseIM can accept client sessions over vanilla XMPP, REST API and SSE, as well as Websockets, and BOSH (HTTP long-polling).
 
@@ -44,6 +44,7 @@ For a quick start just download:
 
 * The [pre-built packages](https://www.erlang-solutions.com/resources/download.html) that suit your platform (Ubuntu, Debian, CentOS, and macOS)
 * The [Docker image](https://hub.docker.com/r/mongooseim/mongooseim/): [https://hub.docker.com/r/mongooseim/mongooseim/](https://hub.docker.com/r/mongooseim/mongooseim/) (source code repository: [https://github.com/esl/mongooseim-docker](https://github.com/esl/mongooseim-docker))
+* The [Helm chart](https://artifacthub.io/packages/helm/mongoose/mongooseim) ([source code repository](https://github.com/esl/MongooseHelm))
 
 ## Public testing
 
@@ -58,9 +59,9 @@ Check out our test results:
 
 ## Documentation
 
-Up-to-date documentation for the MongooseIM master branch can be found on ReadTheDocs: [https://esl.github.io/MongooseDocs/latest/](https://esl.github.io/MongooseDocs/latest/).
+See the documentation for the latest releases:
 
-Latest releases:
+* [Master](https://esl.github.io/MongooseDocs/latest/)
 * [4.2.0](https://esl.github.io/MongooseDocs/4.2.0/)
 * [4.1.0](https://esl.github.io/MongooseDocs/4.1.0/)
 * [4.0.1](https://esl.github.io/MongooseDocs/4.0.1/)
@@ -73,22 +74,20 @@ Latest releases:
 * [3.1.1](https://esl.github.io/MongooseDocs/3.1.1/)
 * [3.0.1](https://esl.github.io/MongooseDocs/3.0.1/)
 
-
 **MongooseIM documentation highlights:**
 
 When developing new features/modules, please make sure you add basic documentation to the 'doc/' directory, and add a link to your document in 'doc/README.md.'
 
-* [Tutorials](https://esl.github.io/MongooseDocs/latest/user-guide/How-to-build/). Learn how to:
-    * [Build MongooseIM from source code](doc/user-guide/How-to-build.md)
-    * [Set up MongoosePush](doc/user-guide/push-notifications/Push-notifications.md)
-    * [Set up MongooseICE](doc/user-guide/ICE_tutorial.md)
-    * [Build an iOS messaging app](doc/user-guide/iOS_tutorial.md)
-* [User Guide](https://esl.github.io/MongooseDocs/latest/user-guide/ABCs-of-MongooseIM/). Learn all about how to use MongooseIM in your project. Explore its features, supported XEPs, RFCs and database backends, as well as its architecture and deployment strategies.
-* [Configuration](https://esl.github.io/MongooseDocs/latest/Basic-configuration/). Explore some of the available options including database backend configuration, access control lists, listener and extension modules.
+* [Tutorials](https://esl.github.io/MongooseDocs/latest/tutorials/How-to-build/). Learn how to:
+    * [Build MongooseIM from source code](https://esl.github.io/MongooseDocs/latest/tutorials/How-to-build/)
+    * [Set up MongoosePush](https://esl.github.io/MongooseDocs/latest/tutorials/push-notifications/Push-notifications/)
+    * [Set up MongooseICE](https://esl.github.io/MongooseDocs/latest/tutorials/ICE_tutorial/)
+    * [Build an iOS messaging app](https://esl.github.io/MongooseDocs/latest/tutorials/iOS_tutorial/)
+* [User Guide](https://esl.github.io/MongooseDocs/latest/user-guide/Features/). Learn all about how to use MongooseIM in your project. Explore its features, supported XEPs, RFCs and database backends, as well as its architecture and deployment strategies.
+* [Configuration](https://esl.github.io/MongooseDocs/latest/configuration/configuration-files/). Explore available options including database backend configuration, access control lists, listener and extension modules.
 * [REST API](https://esl.github.io/MongooseDocs/latest/rest-api/Client-frontend/). Explore MongooseIM features using our REST API and [Swagger documentation](https://esl.github.io/MongooseDocs/latest/swagger/index.html).
 * [Operation and maintenance](https://esl.github.io/MongooseDocs/latest/operation-and-maintenance/Cluster-management-considerations/). See what to consider when building, monitoring, testing and distributing MongooseIM clusters.
-* [Server developer's guide](doc/developers-guide/Testing-MongooseIM.md). Get all the information you need to expand MongooseIM platform.
-
+* [Server developer's guide](https://esl.github.io/MongooseDocs/latest/developers-guide/Testing-MongooseIM/). Get all the information you need to expand the MongooseIM platform.
 
 ## Participate!
 
@@ -97,5 +96,3 @@ Suggestions, questions, thoughts? Contact us directly:
 * Raise a [GitHub issue](https://github.com/esl/MongooseIM/issues)
 * Email us at <a href='mailto:[email protected]'>[email protected]</a>
 * Follow our [Twitter account](https://twitter.com/MongooseIM)
-* Like our [Facebook page](https://www.facebook.com/MongooseIM/)
-* Subscribe to our [mailing list](https://groups.google.com/d/forum/mongooseim-announce) to receive no more than two monthly emails as well as access to the free and open archives

doc/Contributions.md

@@ -2,7 +2,7 @@ Our contributions to the ecosystem.
 
 ## Third-party opensource projects
 
-### XMPPframework for iOS
+### XMPPFramework for iOS
 
 Available on: [robbiehanson/XMPPFramework](https://github.com/robbiehanson/XMPPFramework)
 
@@ -11,7 +11,7 @@ Available on: [robbiehanson/XMPPFramework](https://github.com/robbiehanson/XMPPF
 * [XEP-0030: Service Discovery](https://github.com/robbiehanson/XMPPFramework/pull/736)
 * [MUC light](https://github.com/robbiehanson/XMPPFramework/pull/750)
 * [Token-based reconnection](https://github.com/robbiehanson/XMPPFramework/pull/758)
-* Revamped README: making people feel like this is a well mantained and up to date framework
+* Revamped README: making people feel like this is a well maintained and up to date framework
 * Created a way to Mock a piece of the framework to improve the way we write tests
 
 ### Smack for Android
@@ -53,7 +53,8 @@ amoc is a simple tool for running massively parallel XMPP tests
 
 Apache license 2.0
 
-Note: amoc stands for "A Murder of Crows"
+!!! Info
+    amoc stands for "A Murder of Crows"
 
 ### exml
 
@@ -75,8 +76,8 @@ See [MongoosePush](https://github.com/esl/MongoosePush) on GitHub for more detai
 
 ### MUC light
 
-MUC stands for Multi-User Chat. [MUC light](../open-extensions/muc_light/) is a presenceless and subscription-based group chat, relying on a simplified version of MUC.
+MUC stands for Multi-User Chat. [MUC light](open-extensions/muc_light.md) is a presenceless and subscription-based group chat, relying on a simplified version of MUC.
 
 ### Token-based reconnection
 
-[Token-based reconnection](../open-extensions/token-reconnection/) (TBR) Reconnection mechanism, for temporary disconnections, using tokens instead of passwords
+[Token-based reconnection](open-extensions/token-reconnection.md) (TBR) Reconnection mechanism, for temporary disconnections, using tokens instead of passwords

doc/History.md

@@ -6,7 +6,20 @@ MongooseIM's birthplace is a private Erlang Solutions' branch of ProcessOne's ej
 What would later become a leading, highly customisable and scalable XMPP platform, originated in a strong idea - storing all internal strings in binaries instead of lists, among other significant improvements.
 
 The change was introduced in 0.1.0 proto-MongooseIM release and 3.0.0-alpha-X series of ejabberd.
-This opened the door for achieving higher performance, lower latency and introducing other subsequent improvements building up to a plaform we are truly proud of.
+This opened the door for achieving higher performance, lower latency and introducing other subsequent improvements building up to a platform we are truly proud of.
+
+### Initial differences from the parent project
+
+This project began its life as a fork of ejabberd v.2.1.8, and later underwent major cleanup, refactoring and optimization:
+
+*   Bringing the project source tree to compliance with OTP project structure recommendations
+*   Swapping `autotools` for the Erlang community-standard build tool `rebar`
+*   Removal of obsolete and/or rarely used modules to reduce maintenance burden
+*   Reduction of runtime memory consumption by refactoring the code
+    to use Erlang's binary data type for string manipulation and storage
+    instead of operating on linked lists of characters
+*   Functional test coverage of the system according to corresponding
+    RFCs and XEPs
 
 ## 2012-2015: Fully independent project growing fast
 

doc/authentication-methods/http.md

@@ -157,23 +157,23 @@ Below you can find some examples of the auth service APIs and MongooseIM-side co
 An Auth token is provided as a password.
 
 * **Service implements:** `check_password`, `user_exists`
-* **MongooseIM config:** [`password.format`](../advanced-configuration/auth.md#authpasswordformat): `plain`, `mod_register` disabled
+* **MongooseIM config:** [`password.format`](../configuration/auth.md#authpasswordformat): `plain`, `mod_register` disabled
 * **Client side:** Must NOT use the `DIGEST-MD5` mechanism; use `PLAIN` instead
 
 #### Central database of plaintext passwords
 
 * **Service implements:** `check_password`, `get_password`, `user_exists`
-* **MongooseIM config:** [`password.format`](../advanced-configuration/auth.md#authpasswordformat): `plain`, `mod_register` disabled
+* **MongooseIM config:** [`password.format`](../configuration/auth.md#authpasswordformat): `plain`, `mod_register` disabled
 * **Client side:** May use any available SASL mechanism
 
 #### Central database able to process SCRAM
 
 * **Service implements:** `get_password`, `user_exists`
-* **MongooseIM config:** [`password.format`](../advanced-configuration/auth.md#authpasswordformat): `scram`, `mod_register` disabled
+* **MongooseIM config:** [`password.format`](../configuration/auth.md#authpasswordformat): `scram`, `mod_register` disabled
 * **Client side:** May use any available SASL mechanism
 
 #### Godlike MongooseIM
 
 * **Service implements:** all methods
-* **MongooseIM config:** [`password.format`](../advanced-configuration/auth.md#authpasswordformat): `scram` (recommended) or `plain`, `mod_register` enabled
+* **MongooseIM config:** [`password.format`](../configuration/auth.md#authpasswordformat): `scram` (recommended) or `plain`, `mod_register` enabled
 * **Client side:** May use any available SASL mechanism

doc/authentication-methods/ldap.md

@@ -20,7 +20,7 @@ Example:
   connection.password = "ldap-admin-password"
 ```
 
-For more details see [outgoing connections](../advanced-configuration/outgoing-connections.md).
+For more details see [outgoing connections](../configuration/outgoing-connections.md).
 
 ### SASL PLAIN
 
@@ -44,7 +44,7 @@ Example:
   connection.servers = ["ldap-server.example.com"]
 ```
 
-For more details see [outgoing connections](../advanced-configuration/outgoing-connections.md).
+For more details see [outgoing connections](../configuration/outgoing-connections.md).
 
 ## Configuration options
 

doc/authentication-methods/pki.md

@@ -3,15 +3,15 @@
 This is a simple authentication method, meant to be used with the `SASL EXTERNAL` mechanism.
 It simply accepts all usernames as long as they are validated by the SASL logic.
 
-## WARNING
-
-Some of its callbacks return hardcoded values, as it's impossible for this backend to properly acquire certain pieces of information.
-These include:
-
-| Function | Hardcoded value | Explanation |
-| ---------- | ----------------- | ----------- |
-| `does_user_exist` | `true` | PKI reponds with `true` to modules checking if user's interlocutor actually exists so e.g. messages to nonexistent users will always be stored by `mod_mam`. This is not necessarily a security threat but something to be aware of. |
-| `dirty_get_registered_users`, `get_vh_registered_users`, `get_vh_registered_users_number` | `[]` | Any metrics or statistics (e.g. available via `mongooseimctl`) related to accounts list or numbers, won't display proper values, as this backend cannot possibly "know" how many users there are. |
+!!! Warning
+    
+    Some of its callbacks return hardcoded values, as it's impossible for this backend to properly acquire certain pieces of information.
+    These include:
+    
+    | Function | Hardcoded value | Explanation |
+    | ---------- | ----------------- | ----------- |
+    | `does_user_exist` | `true` | PKI reponds with `true` to modules checking if user's interlocutor actually exists so e.g. messages to nonexistent users will always be stored by `mod_mam`. This is not necessarily a security threat but something to be aware of. |
+    | `dirty_get_registered_users`, `get_vh_registered_users`, `get_vh_registered_users_number` | `[]` | Any metrics or statistics (e.g. available via `mongooseimctl`) related to accounts list or numbers, won't display proper values, as this backend cannot possibly "know" how many users there are. |
 
 ## Configuration options
 

doc/authentication-methods/rdbms.md

@@ -2,7 +2,7 @@
 
 This authentication method stores user accounts in a relational database, e.g. MySQL or PostgreSQL.
 
-## Configuration
+## Configuration options
 
 The `rdbms` method uses an outgoing connection pool of type `rdbms` with the `default` tag - it has to be defined in the `outgoing_pools` section.
 
@@ -15,7 +15,8 @@ The `rdbms` method uses an outgoing connection pool of type `rdbms` with the `de
 By default querying MongooseIM for the number of registered users uses the `SELECT COUNT` query, which might be slow.
 Enabling this option makes MongooseIM use an alternative query that might be not as accurate, but is always fast.
 
-**Note:** this option is effective only for MySQL and PostgreSQL.
+!!! Note
+    This option is effective only for MySQL and PostgreSQL.
 
 ### Example
 

doc/advanced-configuration/Modules.md → doc/configuration/Modules.md

@@ -24,7 +24,8 @@ The server may use one of the following strategies to handle incoming IQ stanzas
 * **Syntax:** string, one of `"one_queue"`, `"no_queue"`, `"queues"`, or `"parallel"`
 * **Example:** `iqdisc.type = "one_queue"`
 
-**Note:** In the `"queues"` case alone, the following key becomes mandatory:
+!!! Note
+    In the `"queues"` case alone, the following key becomes mandatory:
 
 ### `modules.*.iqdisc.workers`
 * **Syntax:** positive integer
@@ -164,8 +165,9 @@ This does not provide a solution to the forgotten password use case via SMS or e
 ### mod_revproxy
 With this extension, MongooseIM may serve as a reverse proxy.
 
-**Warning:** This module is deprecated and can only be configured with the older, `.cfg` configuration file.
-Please refer to the older versions of the documentation to see how to do this.
+!!! Warning
+    This module is deprecated and can only be configured with the older, `.cfg` configuration file.
+    Please refer to the older versions of the documentation to see how to do this.
 
 ### [mod_roster](../modules/mod_roster.md)
 Roster support, specified in [RFC 6121](http://xmpp.org/rfcs/rfc6121.html).
@@ -189,29 +191,17 @@ Provides support for vCards, as specified in [XEP-0054: vcard-temp](http://xmpp.
 ### [mod_version](../modules/mod_version.md)
 This module provides the functionality specified in [XEP-0092: Software Version](https://xmpp.org/extensions/xep-0092.html).
 
-## Modules supporting dynamic domains
-
-These modules can be enabled when using host types in `modules` or [`host_config.modules`](./host_config.md#host_configmodules) sections:
-
-* [mod_blocking](../modules/mod_blocking.md)
-* [mod_caps](../modules/mod_caps.md)
-* [mod_cache_users](../modules/mod_cache_users.md)
-* [mod_carboncopy](../modules/mod_carboncopy.md)
-* [mod_commands](../modules/mod_commands.md)
-* [mod_disco](../modules/mod_disco.md)
-* [mod_domain_isolation](../modules/mod_domain_isolation.md)
-* [mod_inbox](../modules/mod_inbox.md)
-* [mod_last](../modules/mod_last.md)
-* [mod_mam](../modules/mod_mam.md)
-* [mod_muc](../modules/mod_muc.md)
-* [mod_muc_log](../modules/mod_muc_log.md)
-* [mod_muc_light](../modules/mod_muc_light.md)
-* [mod_muc_light_commands](../modules/mod_muc_light_commands.md)
-* [mod_offline](../modules/mod_offline.md)
-* [mod_offline_stub](../modules/mod_offline_stub.md)
-* [mod_ping](../modules/mod_ping.md)
-* [mod_privacy](../modules/mod_privacy.md)
-* [mod_private](../modules/mod_private.md)
-* [mod_roster](../modules/mod_roster.md)
-* [mod_stream_management](../modules/mod_stream_management.md)
-* [mod_vcard](../modules/mod_vcard.md)
+## Modules incompatible with dynamic domains
+
+There are some modules that don't support dynamic domains for now.
+These must **not** be enabled when using host types in `modules` or [`host_config.modules`](./host_config.md#host_configmodules) sections:
+
+* [mod_event_pusher](../modules/mod_event_pusher.md)
+* [mod_extdisco](../modules/mod_extdisco.md)
+* [mod_global_distrib](../modules/mod_global_distrib.md)
+* [mod_jingle_sip](../modules/mod_jingle_sip.md)
+* [mod_pubsub](../modules/mod_pubsub.md)
+* [mod_push_service_mongoosepush](../modules/mod_push_service_mongoosepush.md)
+* [mod_shared_roster_ldap](../modules/mod_shared_roster_ldap.md)
+
+Please note, that [`s2s`](s2s.md) and the XMPP components (XEP-0114) mechanism, as configured in the [`listen.service` section](listen.md#xmpp-components-listenservice), do not support dynamic domains as well.

doc/advanced-configuration/Services.md → doc/configuration/Services.md

@@ -101,7 +101,7 @@ It is used to synchronise dynamic domains between nodes after starting.
 * **Example:** `db_pool = "my_host_type"`
 
 By default, this service uses the RDBMS connection pool configured with the scope `"global"`.
-You can put a specific host type there to use the pool with the `"host"` or `"single_host"` scope for that particular host type. See the [outgoing connections docs](../advanced-configuration/outgoing-connections.md) for more information about pool scopes.
+You can put a specific host type there to use the pool with the `"host"` or `"single_host"` scope for that particular host type. See the [outgoing connections docs](outgoing-connections.md) for more information about pool scopes.
 
 ### `services.service_domain_db.event_cleaning_interval`