globuzma/canaille-globuzma
1
0
Fork 0
forked from Github-Mirrors/canaille
Code Pull requests Activity

doc: simplify installation instructions

Browse source
This commit is contained in:
Éloi Rivard 2024-08-15 19:40:11 +02:00
parent eee7ba98de
commit fad11e72c4
No known key found for this signature in database
GPG key ID: 7EDA204EA57DD184
2 changed files with 61 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
doc/tutorial/install.rst
View file

@ -31,8 +31,8 @@ Canaille provides different package options:
- `sentry` provides sentry integration to watch Canaille exceptions; - `sentry` provides sentry integration to watch Canaille exceptions;
- `all` provides all the extras above. - `all` provides all the extras above.
Configuration Configure
============= =========
Choose a path where to store your configuration file. You can pass any configuration path with the ``CONFIG`` environment variable. Choose a path where to store your configuration file. You can pass any configuration path with the ``CONFIG`` environment variable.
@ -44,68 +44,22 @@ Choose a path where to store your configuration file. You can pass any configura
You should then edit your configuration file to adapt the values to your needs. Look at the configuration details in the :doc:`configuration <../references/configuration>` page. You should then edit your configuration file to adapt the values to your needs. Look at the configuration details in the :doc:`configuration <../references/configuration>` page.
Install and check Install
================= =======
Automatic schemas installation The :ref:`install command <cli_install>` will apply most of the things needed to get Canaille working.
------------------------------ Depending on the configured :doc:`database <databases>` it will create the SQL tables, or install the LDAP schemas for instance.
If you want to install the LDAP schemas yourself, then you can jump to the manual installation section.
.. code-block:: bash .. code-block:: bash
env CONFIG="$CANAILLE_CONF_DIR/config.toml" "$CANAILLE_INSTALL_DIR/env/bin/canaille" install export CONFIG="$CANAILLE_CONF_DIR/config.toml"
"$CANAILLE_INSTALL_DIR/env/bin/canaille" install
Check
=====
Manual schemas installation After a manual installation, you can check your configuration file using the :ref:`check command <cli_install>`:
---------------------------
LDAP schemas
^^^^^^^^^^^^
As of OpenLDAP 2.4, two configuration methods are available:
- The `deprecated <https://www.openldap.org/doc/admin26/slapdconf2.html>`_ one, based on a configuration file (generally ``/etc/ldap/slapd.conf``);
- The new one, based on a configuration directory (generally ``/etc/ldap/slapd.d``).
Depending on the configuration method you use with your OpenLDAP installation, you need to chose how to add the canaille schemas:
Old fashion: Copy the schemas in your filesystem
""""""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: bash .. code-block:: bash
test -d /etc/openldap/schema && sudo cp "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*" /etc/openldap/schema "$CANAILLE_INSTALL_DIR/env/bin/canaille" check
test -d /etc/ldap/schema && sudo cp "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*" /etc/ldap/schema
sudo service slapd restart
New fashion: Use slapadd to add the schemas
"""""""""""""""""""""""""""""""""""""""""""
Be careful to stop your ldap server before running ``slapadd``
.. code-block:: bash
sudo service slapd stop
sudo -u openldap slapadd -n0 -l "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*.ldif"
sudo service slapd start
Generate the key pair
---------------------
You must generate a keypair that canaille will use to sign tokens.
You can customize those commands, as long as they match the ``JWT`` section of your configuration file.
.. code-block:: bash
sudo openssl genrsa -out "$CANAILLE_CONF_DIR/private.pem" 4096
sudo openssl rsa -in "$CANAILLE_CONF_DIR/private.pem" -pubout -outform PEM -out "$CANAILLE_CONF_DIR/public.pem"
Configuration check
^^^^^^^^^^^^^^^^^^^
After a manual installation, you can check your configuration file with the following command:
.. code-block:: bash
env CONFIG="$CANAILLE_CONF_DIR/config.toml" "$CANAILLE_INSTALL_DIR/env/bin/canaille" check

49
doc/tutorial/troubleshooting.rst
View file

@ -7,3 +7,52 @@ The web interface throws unuseful error messages
Unless the current user has admin :class:`permissions <canaille.core.configuration.Permission>`, or the installation is in :attr:`~canaille.app.configuration.RootSettings.DEBUG` mode, error messages won't be too technical. Unless the current user has admin :class:`permissions <canaille.core.configuration.Permission>`, or the installation is in :attr:`~canaille.app.configuration.RootSettings.DEBUG` mode, error messages won't be too technical.
For instance, you can see *The request you made is invalid*. For instance, you can see *The request you made is invalid*.
To enable detailed error messages, you can **temporarily** enable the :attr:`~canaille.app.configuration.RootSettings.DEBUG` configuration parameter. To enable detailed error messages, you can **temporarily** enable the :attr:`~canaille.app.configuration.RootSettings.DEBUG` configuration parameter.
How to manually install LDAP schemas?
=====================================
.. note::
Schema installation can be automatically done using the :ref:`install command <cli_install>`.
As of OpenLDAP 2.4, two configuration methods are available:
- The `deprecated <https://www.openldap.org/doc/admin26/slapdconf2.html>`_ one, based on a configuration file (generally ``/etc/ldap/slapd.conf``);
- The new one, based on a configuration directory (generally ``/etc/ldap/slapd.d``).
Depending on the configuration method you use with your OpenLDAP installation, you need to chose how to add the canaille schemas:
Old fashion: Copy the schemas in your filesystem
------------------------------------------------
.. code-block:: bash
test -d /etc/openldap/schema && sudo cp "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*" /etc/openldap/schema
test -d /etc/ldap/schema && sudo cp "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*" /etc/ldap/schema
sudo service slapd restart
New fashion: Use slapadd to add the schemas
-------------------------------------------
Be careful to stop your ldap server before running ``slapadd``
.. code-block:: bash
sudo service slapd stop
sudo -u openldap slapadd -n0 -l "$CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/backends/ldap/schemas/*.ldif"
sudo service slapd start
How to manually generate the OIDC keypair?
==========================================
.. note::
The keypair generation can be automatically done using the :ref:`install command <cli_install>`.
Canaille needs a key pair to sign OIDC tokens.
You can customize those commands, as long as they match the ``JWT`` section of your configuration file.
.. code-block:: bash
sudo openssl genrsa -out "$CANAILLE_CONF_DIR/private.pem" 4096
sudo openssl rsa -in "$CANAILLE_CONF_DIR/private.pem" -pubout -outform PEM -out "$CANAILLE_CONF_DIR/public.pem"