DOC: tutorial: custom content

Add tutorial to add custom custom content (leapp repositories, actors,
etc.) on the system to be used during the IPU process.

docs/source/tutorials/custom-content.md

@@ -0,0 +1,118 @@
+# Creating custom content for IPU
+
+The official leapp repositories for in-place upgrade cover usually only RPM packages
+signed by official distribution's GPG keys. Other content (third-party RPMs -
+including EPEL, custom installed content, ..) needs to be covered separately.
+In some cases there is not a better (or other) way than creating additional actors
+to customize the IPU process.
+
+To simplify troubleshooting for us and others (and prevent other possible problems)
+we request custom actors to be installed into own leapp repositories
+on the system which should be located inside the `/usr/share/leapp-repository/custom-repositories/`
+directory.
+
+This guide explains how to create custom leapp actors and repositories on the system and
+how to ensure they are discovered and processed by Leapp. For the simplification
+consider that custom content includes third-party content as well.
+
+For the purpose of this guide install the `snactor` utility.
+
+## Create custom repository
+
+To keep it simple, instructions covers the creation of the custom leapp repository
+on the system with installed `leapp` and `leapp-upgrade-*` (and `snactor`) packages.
+For in-place upgrade of RHEL systems see also [official instructions](https://access.redhat.com/articles/4977891#create-custom-actor).
+
+```{note}
+If you want to create new leapp repository in your develpment environment without
+installing `leapp-upgrade-*` packages, you will need clone the leapp-repository
+git repo and register related leapp repositories using `snactor` manually. See
+`snactor repo find --help` for more info. 
+```
+
+
+1. Go to the directory where a new Leapp repository should be created:
+```shell
+cd /usr/share/leapp-repository/custom-repositories/
+```
+
+2. Create a new Leapp repository:
+```shell
+snactor repo new <repository_name>
+```
+
+Read carefully [Naming Convention](#naming-convention) section to choose a right
+name to prevent possible conflicts with other content.
+
+```{note}
+Note that snactor does not have to create automatically whole directory structure
+inside the repository (directories like `tools`, `libraries`, etc...). Create
+any needed directories manually. See [Repository directory layout](https://leapp.readthedocs.io/en/latest/repository-dir-layout.html) for more info.
+```
+
+3. Go to the newly created leapp repository:
+```shell
+cd /usr/share/leapp-repository/custom-repositories/<repository_name>
+```
+
+4. [Link other needed repositories](https://leapp.readthedocs.io/en/latest/repo-linking.html)
+into the newly created custom repository. You should always link following repositories:
+```shell
+snactor repo link --path /usr/share/leapp-repository/repositories/system_upgrade/common
+snactor repo link --path /usr/share/leapp-repository/repositories/common
+```
+In case you need any content present in particular `.../system_upgrade/elXtoelY`
+repository, link it too.
+
+```{note}
+All defined links are understood as requirements for the correct functioning
+of the custom leapp repository. E.g. adding dependency on `system_upgrade_el8toel9`
+repository means that the custom repository can bee installed and used only on
+RHEL 8 (inluding RHEL-like) system as the `system_upgrade_el8toel9` is present
+only there.
+```
+
+5. Create a symlink in `/etc/leapp/repos.d/` to register your repository for leapp:
+```shell
+ln -s /usr/share/leapp-repository/custom-repositories/<repository_name> /etc/leapp/repos.d/
+```
+
+```{note}
+This step is required to be done just on the system where the custom repository
+is installed so leapp will discover the repository.
+```
+
+Note that such a created leapp repository can be installed to other systems as it is,
+just the symlink needs to be always created as well (step `5`).
+
+## Create custom actor
+
+To create custom actors inside the newly created custom leapp repository follow
+the tutorial [Writing an Actor for Leapp Upgrade](howto-first-actor-upgrade)
+and read the **Naming convention** section below.
+
+
+## Naming convention
+
+The system can contain number of leapp repositories and actors. Also, the leapp framework
+is focused on making lives of developers as simple as possible, but it is
+paid by missing namespacing. So developers are responsible to choose wisely
+names of their leapp repositories, actors, models, and libraries to ensure
+they do not conflict with others. To help you to prevent possible conflicts
+we propose following conventions:
+
+1. If you create solutions for your personal use that will not be shared with
+others, use e.g. the `my_custom_` prefix for the repository name. Similar can be applied
+for all other leapp entities (actors, models, libraries, ...).
+2. If you are SW vendor and want to create solution for your customers,
+make the name of your company or product part of the leapp repository name.
+3. Do not use generic names for leapp actors, models, and repositories. E.g.
+creating actor that checks MySQL configuration with the `check_config` or `check_database` names
+are really bad. `check_config_mysql` or `check_config_mysql_vX` is better but if multiple
+products on market use the same MySQL version X and can be present on the same system,
+it's still not ideal. So e.g. `check_config_mysql_<company>`
+or `check_config_mysql_<product>`, where product is your unique product you deliver,
+is much better option.
+4. Similar applies for libraries. Creating library `databases` or `mysql` is too much
+generic.
+

docs/source/tutorials/index.rst

@@ -1,13 +1,17 @@
 Tutorials
 =========
 
+Tutorials here are focused on In-Place Upgrades with leapp repositories
+covered by the `leapp-repository <https://github.com/oamg/leapp-repository>`_ project.
+
 .. toctree::
     :maxdepth: 4
     :caption: Contents:
     :glob:
 
-    templates/index
     howto-first-actor-upgrade
+    custom-content
+    templates/index
     troubleshooting-debugging
 
 .. Indices and tables