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 ``${auth: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 ``service-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 ``${auth:client_id}`` and ``${auth: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 ``${auth:oauth_provider}`` and ``${auth: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``.