docs: split faq into multiple files

docs/faq/web.rst

@@ -0,0 +1,145 @@
+Web service
+-----------
+
+How to setup web service
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp python-aiohttp-jinja2 python-aiohttp-apispec>=3.0.0 python-aiohttp-cors
+
+#. 
+   Configure service:
+
+   .. code-block:: ini
+
+      [web]
+      port = 8080
+
+#. 
+   Start the web service ``systemctl enable --now ahriman-web``.
+
+How to enable basic authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Install dependencies 😊:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp-security python-aiohttp-session python-cryptography
+
+#. 
+   Configure the service to enable authorization:
+
+   .. code-block:: ini
+
+      [auth]
+      target = configuration
+      salt = somerandomstring
+
+   The ``salt`` parameter is optional, but recommended, and can be set to any (random) string.
+
+#.
+   In order to provide access for reporting from application instances you can (the recommended way) use unix sockets by the following configuration (note, that it requires ``python-requests-unixsocket2`` package to be installed):
+
+   .. code-block:: ini
+
+      [web]
+      unix_socket = /run/ahriman/ahriman-web.sock
+
+   This socket path must be available for web service instance and must be available for all application instances (e.g. in case if you are using docker container - see above - you need to make sure that the socket is passed to the root filesystem).
+
+   By the way, unix socket variable will be automatically set in case if ``--web-unix-socket`` argument is supplied to the ``setup`` subcommand.
+
+   Alternatively, you need to create user for the service:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full api
+
+   This command will ask for the password, just type it in stdin; **do not** leave the field blank, user will not be able to authorize, and finally configure the application:
+
+   .. code-block:: ini
+
+      [status]
+      username = api
+      password = pa55w0rd
+
+#.
+   Create end-user with password:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full my-first-user
+
+#.
+   Restart web service ``systemctl restart ahriman-web``.
+
+Using PAM authentication
+""""""""""""""""""""""""
+
+There is also ability to allow system users to log in. To do so, the following configuration have to be set:
+
+.. code-block:: ini
+
+   [auth]
+   target = pam
+   full_access_group = wheel
+
+With this setup, every user (except root) will be able to log in by using system password. If user belongs to the ``wheel`` group, the full access will be automatically granted. It is also possible to manually add, block user or change user rights via usual user management process.
+
+How to enable OAuth authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Create OAuth web application, download its ``client_id`` and ``client_secret``.
+
+#.
+   Guess what? Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp-security python-aiohttp-session python-cryptography python-aioauth-client
+
+#. 
+   Configure the service:
+
+   .. code-block:: ini
+
+      [auth]
+      target = oauth
+      client_id = ...
+      client_secret = ...
+
+      [web]
+      address = https://example.com
+
+   Configure ``oauth_provider`` and ``oauth_scopes`` in case if you would like to use different from Google provider. Scope must grant access to user email. ``web.address`` is required to make callback URL available from internet.
+
+#. 
+   If you are not going to use unix socket, you also need to create service user (remember to set ``auth.salt`` option before if required):
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add --as-service -r full api
+
+#. 
+   Create end-user:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full my-first-user
+
+   When it will ask for the password leave it blank.
+
+#.
+   Restart web service ``systemctl restart ahriman-web``.
+
+How to implement own interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can write your own interface by using API which is provided by the web service. Full autogenerated API documentation is available at ``http://localhost:8080/api-docs``.