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;

  • sql provides the dependencies to enable the Postgresql or Mysql backends;

  • sentry provides sentry integration to watch Canaille exceptions;

  • all provides all the extras above.

They can be installed with:

pip install "canaille[front,oidc,sql]"

Configure

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

The install command will apply most of the things needed to get Canaille working. Depending on the configured database it will create the SQL tables, or install the LDAP schemas for instance.

export CONFIG="$CANAILLE_CONF_DIR/config.toml"
"$CANAILLE_INSTALL_DIR/env/bin/canaille" install

Check

After a manual installation, you can check your configuration file using the check command:

"$CANAILLE_INSTALL_DIR/env/bin/canaille" check