mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-10-31 13:53:41 +00:00
Evgenii Alekseev
93ce7f9a51
* move argument parsers to handlers themselves
* use hatchling instead of flit
* Revert "use hatchling instead of flit"
This reverts commit d18d146d79.
* add package-splitt script
* replace simplify walk method
* split packages
* explicitly install packages
* separate support triggers from main package
* add docs examples
* sort actions
* docs update
* add metapackage
* review fixes
146 lines
4.0 KiB
ReStructuredText
146 lines
4.0 KiB
ReStructuredText
Web service
|
|
-----------
|
|
|
|
How to setup web service
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
#.
|
|
Install web service:
|
|
|
|
.. code-block:: shell
|
|
|
|
yay -S ahriman-web
|
|
|
|
#.
|
|
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``.
|