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