Installation¶
Warning
Canaille is under heavy development and may not fit a production environment yet.
The installation of canaille consist in several steps, some of which you can do manually or with command line tool:
Get the code¶
As the moment there is no distribution package for canaille. However, it can be installed with the pip
package manager.
Let us choose a place for the canaille environment, like /opt/canaille/env
.
export CANAILLE_INSTALL_DIR=/opt/canaille
sudo mkdir --parents "$CANAILLE_INSTALL_DIR"
sudo virtualenv --python=python3 "$CANAILLE_INSTALL_DIR/env"
sudo "$CANAILLE_INSTALL_DIR/env/bin/pip" install "canaille[all]"
Extras¶
Canaille provides different package options:
front provides all the things needed to produce the user interface;
oidc provides the dependencies to perform OAuth2/OIDC authentication;
ldap provides the dependencies to enable the LDAP backend;
sentry provides sentry integration to watch Canaille exceptions;
all provides all the extras above.
Configuration¶
Choose a path where to store your configuration file. You can pass any configuration path with the CONFIG
environment variable.
export CANAILLE_CONF_DIR=/etc/canaille
sudo mkdir --parents "$CANAILLE_CONF_DIR"
sudo cp $CANAILLE_INSTALL_DIR/env/lib/python*/site-packages/canaille/config.sample.toml "$CANAILLE_CONF_DIR/config.toml"
You should then edit your configuration file to adapt the values to your needs. Look at the configuration details in the Configuration page.
Install and check¶
Automatic schemas installation¶
If you want to install the LDAP schemas yourself, then you can jump to the manual installation section.
env CONFIG="$CANAILLE_CONF_DIR/config.toml" "$CANAILLE_INSTALL_DIR/env/bin/canaille" install
Manual schemas installation¶
LDAP schemas¶
As of OpenLDAP 2.4, two configuration methods are available:
The deprecated 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¶
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
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.
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:
env CONFIG="$CANAILLE_CONF_DIR/config.toml" "$CANAILLE_INSTALL_DIR/env/bin/canaille" check