From 148b8f133f144f4133c52405439fcce61bc35c89 Mon Sep 17 00:00:00 2001 From: Johannes Meyer Date: Wed, 11 Oct 2023 15:14:11 +0200 Subject: [PATCH] doc: Adjust accordingly to our new packaging docs --- doc/01-About.md | 7 +++--- doc/02-Installation.md | 32 +++++++++++++----------- doc/02-Installation.md.d/From-Source.md | 15 +++++++++++ doc/03-Getting-Started.md | 13 ++++------ doc/04-Create-your-first-process-node.md | 6 ++--- doc/05-Importing-Processes.md | 9 +++---- doc/06-Customize-Node-Order.md | 9 +++---- doc/09-Operators.md | 12 ++++----- doc/12-Web-Components-Breadcrumb.md | 9 +++---- doc/13-Web-Components-Tile-Renderer.md | 3 +-- doc/14-Web-Components-Tree-Renderer.md | 3 +-- doc/16-Add-To-Dashboard.md | 6 ++--- doc/21-Store-Config.md | 6 ++--- doc/22-Upload-Config.md | 8 +++--- doc/31-Permissions.md | 9 +++---- doc/81-History.md | 11 +++----- 16 files changed, 74 insertions(+), 84 deletions(-) create mode 100644 doc/02-Installation.md.d/From-Source.md diff --git a/doc/01-About.md b/doc/01-About.md index 13eb925..44672b4 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -1,10 +1,9 @@ -# Icinga Business Process Modelling +# Icinga Business Process Modeling If you want to visualize and monitor hierarchical business processes based on -any or all objects monitored by Icinga, the Icinga Web 2 business process -module is the way to go. +objects monitored by Icinga, Icinga Business Process Modeling is the solution. -[![Dashboard](screenshot/16_dashboard/1603_businessprocesses_on_dashboard.png)](doc/16-Add-To-Dashboard.md) +[![Dashboard](screenshot/16_dashboard/1603_businessprocesses_on_dashboard.png)](16-Add-To-Dashboard.md) Want to create custom process-based dashboards? Trigger notifications at process or sub-process level? Provide a quick top-level view for thousands of diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 54fb9e9..6d479b1 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,20 +1,24 @@ -# Installation + +# Installing Icinga Business Process Modeling -## Requirements +The recommended way to install Icinga Business Process Modeling is to use prebuilt packages for +all supported platforms from our official release repository. +Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is required to run Icinga +Business Process Modeling and if it is not already set up, it is best to do this first. -* PHP (>= 7.2) -* Icinga Web 2 (>= 2.9) -* Icinga Web 2 libraries: - * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.8) - * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.11) -* Icinga Web 2 modules: - * The `monitoring` or `icingadb` module needs to be configured and enabled. +The following steps will guide you through installing and setting up Icinga Business Process Modeling. + + -## Install Icinga Business Process Modeling +## Installing the Package -Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation). -Use `businessprocess` as name. +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-businessprocess` package +or install [from source](02-Installation.md.d/From-Source.md). + -## Create your first Business Process definition +## Configuring Icinga Business Process Modeling -That's it, *Business Process* is now ready for use. Please read more on [how to get started](03-Getting-Started.md). +That's it, Icinga Business Process Modeling is now ready to use. +Please read more on [how to get started](03-Getting-Started.md). + diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 0000000..6941d54 --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,15 @@ +# Installing Icinga Business Process Modeling from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web/latest/doc/08-Modules/#installation) from source. +Make sure you use `businessprocess` as the module name. The following requirements must also be met. + +## Requirements + +* PHP (≥7.2) +* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +* [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0) +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.8.0) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11.0) + + diff --git a/doc/03-Getting-Started.md b/doc/03-Getting-Started.md index e90dfc2..baacde0 100644 --- a/doc/03-Getting-Started.md +++ b/doc/03-Getting-Started.md @@ -1,13 +1,11 @@ -Getting Started -=========================================== +# Getting Started -Once you enable the *Business Process* module, it will pop up in your menu. -When you click on it, it will show you a new Dashboard: +Once you enable Icinga Business Process Modeling, it will pop up in your menu. +If you click on it, it will show you a new Dashboard: ![Empty Dashboard](screenshot/03_getting-started/0201_empty-dashboard.png) -A new Business Process configuration -------------------------------------------- +## A new Business Process configuration From here we choose to create a new *Business Process configuration*: @@ -65,8 +63,7 @@ first five configurations a user is allowed to see will be shown there: That's all for now, click `Add` to store your new (still empty) Business Process configuration. -Empty configuration -=================== +## Empty configuration You are redirected to your newly created Business Process configuration: diff --git a/doc/04-Create-your-first-process-node.md b/doc/04-Create-your-first-process-node.md index f5b8b84..ad3273d 100644 --- a/doc/04-Create-your-first-process-node.md +++ b/doc/04-Create-your-first-process-node.md @@ -1,5 +1,4 @@ -Create your first Business Process Node -================================================================================== +# Create your first Business Process Node A *Business Process Node* consists of a *name*, *title*, an *operator* and one or more child nodes. It can be a Root Node, child node of other Business Process @@ -7,8 +6,7 @@ Nodes - or both. ![Empty Config](screenshot/04_first-root-node/0301_empty-config.png) -Configuring our first node --------------------------- +## Configuring our first node To create our first *Business Process Node* we click the *Add* button. This leads to the related configuration form: diff --git a/doc/05-Importing-Processes.md b/doc/05-Importing-Processes.md index fccca97..3095bbf 100644 --- a/doc/05-Importing-Processes.md +++ b/doc/05-Importing-Processes.md @@ -1,5 +1,4 @@ -Importing Processes -=================================================== +# Importing Processes To avoid redundancy and make complex *Business Process Configurations* easier to maintain it is possible to import processes from other configurations. @@ -9,8 +8,7 @@ import processes into the root level. ![Subprocesses Only](screenshot/05_importing_nodes/0401_subprocesses_only.png) -Importing a Process -------------------- +## Importing a Process Once the related configuration form is open, choose `Existing Process` and wait for the form to refresh. @@ -37,8 +35,7 @@ to save your changes! ![Import Successful](screenshot/05_importing_nodes/0405_import_successful.png) -Navigation with Imported Processes ----------------------------------- +## Navigation with Imported Processes ### Seamless Breadcrumbs diff --git a/doc/06-Customize-Node-Order.md b/doc/06-Customize-Node-Order.md index a4373f2..880eaa6 100644 --- a/doc/06-Customize-Node-Order.md +++ b/doc/06-Customize-Node-Order.md @@ -1,5 +1,4 @@ -Customize Node Order -===================================================== +# Customize Node Order By default all nodes are ordered alphabetically while viewing them in the UI. Though, it is also possible to order nodes entirely manually. @@ -9,8 +8,7 @@ Though, it is also possible to order nodes entirely manually. > Once manual order is applied (no matter where) alphabetical order is > disabled for the entire configuration. -Reorder by Drag'n'Drop ----------------------- +## Reorder by Drag'n'Drop Make sure to unlock the configuration first to be able to reorder nodes. @@ -34,8 +32,7 @@ The tree view also has an advantage the tile view has not. It is possible to move nodes within the entire hierarchy. But remember to unfold processes first, if you want to move a node into them. -File Format Extensions ----------------------- +## File Format Extensions The configuration file format has slightly been changed to accommodate the new manual order. Though, previous configurations are perfectly upwards compatible. diff --git a/doc/09-Operators.md b/doc/09-Operators.md index ba2f51d..8d54ba3 100644 --- a/doc/09-Operators.md +++ b/doc/09-Operators.md @@ -1,15 +1,15 @@ -# Operators +# Operators Every Business Process requires an Operator. This operator defines its behaviour and specifies how its very own state is going to be calculated. -## AND +## AND The `AND` operator selects the **WORST** state of its child nodes: ![And Operator](screenshot/09_operators/0901_and-operator.png) -## OR +## OR The `OR` operator selects the **BEST** state of its child nodes: @@ -17,7 +17,7 @@ The `OR` operator selects the **BEST** state of its child nodes: ![Or Operator #2](screenshot/09_operators/0903_or-operator-without-ok.png) -## XOR +## XOR The `XOR` operator shows OK if only one of n children is OK at the same time. In all other cases the parent node is CRITICAL. Useful for a service on n servers, only one of which may be running. If both were running, @@ -27,7 +27,7 @@ race conditions and duplication of data could occur. ![Xor Operator #2](screenshot/09_operators/0907_xor-operator-not-ok.png) -## DEGRADED +## DEGRADED The `DEGRADED` operator behaves like an `AND`, but if the resulting state is **CRITICAL** it transforms it into a **WARNING**. @@ -36,7 +36,7 @@ analysis of the statuses. ![Degraded Operator](screenshot/09_operators/0905_deg-operator.jpg) -## MIN n +## MIN n The `MIN` operator selects the **WORST** state out of the **BEST n** child node states: diff --git a/doc/12-Web-Components-Breadcrumb.md b/doc/12-Web-Components-Breadcrumb.md index a9811da..27391f0 100644 --- a/doc/12-Web-Components-Breadcrumb.md +++ b/doc/12-Web-Components-Breadcrumb.md @@ -1,5 +1,4 @@ -Web Components: Breadcrumb -================================================================ +# Web Components: Breadcrumb All Business Process renderers show a **breadcrumb** component to always give you a quick indication of your current location. @@ -24,8 +23,7 @@ column view to make it obvious that you moved to another context. It is also perfectly legal to open any of the available links in a new browser tab or window. -Available actions below the Breadcrumb --------------------------------------- +## Available actions below the Breadcrumb ### Choose a renderer @@ -60,8 +58,7 @@ settings for the your currently loaded *Business Process Configuration*: But there is more. When unlocked, all nodes provide links allowing you to modify or to delete them. Host/Service Nodes now allow you to simulate a specific state. -Other main actions ------------------- +## Other main actions ### Add content to your Dashboard diff --git a/doc/13-Web-Components-Tile-Renderer.md b/doc/13-Web-Components-Tile-Renderer.md index d362f33..4d5df8c 100644 --- a/doc/13-Web-Components-Tile-Renderer.md +++ b/doc/13-Web-Components-Tile-Renderer.md @@ -1,5 +1,4 @@ -Web Components: Tile Renderer -====================================================================== +# Web Components: Tile Renderer The default Business Process *Renderer* is the *Tile Renderer*. It always shows one level of your tree, enriched with badges giving some hint on lower level diff --git a/doc/14-Web-Components-Tree-Renderer.md b/doc/14-Web-Components-Tree-Renderer.md index 7bf2137..b761360 100644 --- a/doc/14-Web-Components-Tree-Renderer.md +++ b/doc/14-Web-Components-Tree-Renderer.md @@ -1,5 +1,4 @@ -Web Components: Tree Renderer -====================================================================== +# Web Components: Tree Renderer The main advantage of the *Tree Renderer* is that it is able to show all nodes of Business Process trees at once. This works fine even for huge trees with lots diff --git a/doc/16-Add-To-Dashboard.md b/doc/16-Add-To-Dashboard.md index deda692..4b9f8a8 100644 --- a/doc/16-Add-To-Dashboard.md +++ b/doc/16-Add-To-Dashboard.md @@ -1,5 +1,4 @@ -Show Processes on a Dashboard -========================================================== +# Show Processes on a Dashboard When being in *Locked mode*, you can add any Business Process at top or sub level to any Icinga Web 2 Dashboard. The related link can be found in the Tab bar: @@ -13,8 +12,7 @@ want to create a dedicated Dashboard as shown in this example: ![Add to Dashboard - Form](screenshot/16_dashboard/1602_add_to_dashboard-form.png) -Want more? ----------- +## Want more? Head on and add multiple Business Processes to your Dashboard to show all of them at once: diff --git a/doc/21-Store-Config.md b/doc/21-Store-Config.md index 709c413..a8380e7 100644 --- a/doc/21-Store-Config.md +++ b/doc/21-Store-Config.md @@ -1,5 +1,4 @@ -Store your Configuration -================================================= +# Store your Configuration Changes to your *Business Process Configuration* are added to a stack and will not be stored immediately. In case there are pending unstored changes, this will @@ -13,8 +12,7 @@ you created your [very first configuration](03-Getting-Started.md): ![Store Config](screenshot/21_store-config/2102_Store-Config.png) -Config Diff ------------ +## Config Diff If unsure what changes you're going to store, you can still check the *Config Diff* before finally storing to disk: diff --git a/doc/22-Upload-Config.md b/doc/22-Upload-Config.md index 07e6b63..2afdb01 100644 --- a/doc/22-Upload-Config.md +++ b/doc/22-Upload-Config.md @@ -1,5 +1,4 @@ -Upload a Configuration File -===================================================== +# Upload a Configuration File You can upload a formerly downloaded or even a manually created file directly through the web frontend. Given sufficient permissions, the Dashboard provides @@ -7,14 +6,13 @@ a related link: ![From Dashboard to Upload](screenshot/22_upload-config/2201_go-to-upload.png) -Chose a file ------------- +## Chose a file This can be any file: ![Choose a File](screenshot/22_upload-config/2202_choose-file.png) -It should be valid of course, but don't worry - the *Business Process* module +It should be valid of course, but don't worry - Icinga Business Process Modeling protects you from syntax errors: ![Syntax Error](screenshot/22_upload-config/2203_syntax-error.png) diff --git a/doc/31-Permissions.md b/doc/31-Permissions.md index 47c9ca1..b6b8b98 100644 --- a/doc/31-Permissions.md +++ b/doc/31-Permissions.md @@ -1,10 +1,8 @@ -Permission System -================================================= +# Permission System The permission system of the module is based on permissions and restrictions. -Permissions ------------ +## Permissions The module has five levels of permissions: @@ -14,8 +12,7 @@ The module has five levels of permissions: * Permission to view all business processes regardless restrictions. (`businessprocess/showall`) * Full permissions. (`businessprocess/*`) -Restrictions ------------ +## Restrictions There are two ways to configure restrictions: prefix-based and access controls diff --git a/doc/81-History.md b/doc/81-History.md index 8366163..82a4024 100644 --- a/doc/81-History.md +++ b/doc/81-History.md @@ -1,15 +1,13 @@ -Project History -=============== +# Project History -The Business Process module is based on the ideas of the Nagios(tm) [Business +Icinga Business Process Modeling is based on the ideas of the Nagios(tm) [Business Process AddOn](http://bp-addon.monitoringexchange.org/) written by Bernd Strößenreuther. We always loved its simplicity, and while it looks pretty oldschool right now there are still many shops happily using it in production. ![BpAddOn Overview](screenshot/81_history/8101_bpaddon-overview.png) -Compatibility -------------- +## Compatibility We fully support the BPaddon configuration language and will continue to do so. It's also perfectly valid to run both products in parallel based on the very same @@ -33,8 +31,7 @@ backends like SQL databases or the Icinga 2 DSL. This would make it easier to distribute configuration in large environments. -Improvements ------------- +## Improvements Major focus has been put on execution speed. So while the Web integration shows much more details at once and is able to display huge unfolded trees, it should