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]"


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.


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