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