__netbox{,_uwsgi}: updated manpages

Mostly added notes of what does not work that well.

type/__netbox/man.rst

@@ -16,7 +16,7 @@ It setup systemd unit files for the services `netbox` and `netbox-rq`. The
 `netbox` service only wrap all netbox related services, e.g. restarting and
 so one will be delegated to all related services.
 
-The application is still not accessable because WSGI server is required. To
+The application is still not accessable because a WSGI server is required. To
 access the application through WSGI, uWSGI or Gunicorn can be used. The setup
 can be done via there own types `__netbox_gunicorn` and `__netbox_uwsgi`.
 
@@ -236,23 +236,21 @@ If you not setup ldap authentification, you may be interested into how to
 <https://netbox.readthedocs.io/en/stable/installation/3-netbox/#create-a-super-user>`
 directly on the machine to be able to access and use NetBox.
 
-If you change a configuration, the database may go corrupt if two instances of
+You may also be interested of writing a own type which handles the creation of
-the application are running with different configurations at the same time.
+the super user. To do this non-interactivly, see the ansible role as `reference
-This most commonly happens when the WSGI server and RQ-worker restarts after a
+<https://github.com/lae/ansible-role-netbox/blob/18f46a3345f100936c5116abe716c480e1886676/vars/main.yml#L15>`.
-configuration change. This occours in the following case for example:
 
-.. code-block:: sh
+If you change the secret key while the netbox instance is running, there is a
+time frame where the access to the application corrupts the whole database.
+Then, you need to restore a backup or wipe the database.
 
-   systemctl restart gunicorn-netbox  # WSGI-server already online with new
+Currently, the cause is not clear, but it should work if you do not touch
-                                      # configuration after this command.
+netbox while the configuration is done (do not shut it down, too). It only
-   systemctl restart netbox-rq  # RQ-Worker still worked with the old
+applies for changes of the secret key, which not happen normally.
-                                # configuration till here.
 
-This type handles the restart of both services correctly to avoid such database
+Maybe the `--restart` flag for the `__systemd_unit` types is not the best idea,
-corruptions. To safely manual restart the whole netbox instance manual, simply
+but avoids that the changes will not be applied. It could be solved if the type
-restart all services in one ``systemctl restart netbox`` command, as it ensures
+would send messages from his actions.
-that first all services are shut down before starting one of them. The service
-``netbox`` wraps all required services that are available.
 
 
 SEE ALSO

type/__netbox_uwsgi/man.rst

@@ -129,6 +129,7 @@ EXAMPLES
 
     # with multiple protocols
     #  parameter `--bind-to` will be ignored
+    #  avoids systemd sockets, but can handle multiple protocols
     __netbox $args
     require="__netbox" __netbox_uwsgi --uwsgi-bind 0.0.0.0:3031 \
                                       --http-bind 0.0.0.0:8080 \
@@ -150,6 +151,20 @@ EXAMPLES
     require="__netbox_uwsgi" __systemd_service uwsgi-netbox --state stopped
 
 
+NOTES
+-----
+If systemd sockets are used, uwsgi can not be reloaded because it does not
+handle the socket correctly. It works by completly restarting uwsgi (because
+it is near the same cause of the systemd socket) or tweaking the service unit
+with the line ``StandardInput=socket``, which limits you to only one address
+to bind to (else, the service will not start).
+
+Maybe someone is interested in enabling log files, because the "log to stdout"
+is not the fanciest approach (because it is shown in the journal). See the
+`uwsgi documentation <https://uwsgi.readthedocs.io/en/latest/Logging.html>` for
+reference.
+
+
 SEE ALSO
 --------
 `uWSGI Documentation <https://uwsgi-docs.readthedocs.io/en/latest/>`_