Installation¶
This page describes how to get and set-up Canaille.
I have no time, spare me the details !
wget https://github.com/yaal-coop/canaille/releases/download/0.0.64/canaille -o canaille chmod +x canaille export CONFIG=/path/to/my/config.toml canaille config dump $EDITOR $CONFIG canaille install canaille config check canaille create user --user-name admin --password admin --emails admin@mydomain.example --given-name George --family-name Abitbol
Get the code¶
Binaries¶
Canaille provides a ready-to-use single file executable for Linux. The binary installation is the easiest way to get a production-ready Canaille release, though this is not the most customizable. This is generally the recommended method to use Canaille in production.
wget https://github.com/yaal-coop/canaille/releases/download/0.0.64/canaille -o canaille chmod +x canaille
Note
Canaille binaries comes with lesser performances than other installation methods on startup. This is generally not an issue, since Canaille is used as a long-running service, but if this is important for you, you might want to choose another installation method.
Linux packages¶
At the moment, only NixOS provides a Canaille package. For other distros, you must use a different way to install Canaille.
Python package¶
Canaille provides a Python package that you can install with package managers like uv
or pip
.
This is the recommended method if you want fast CLI performances, if you need to customize the dependencies, or if you want to use Canaille in a development environment.
In the following example, we use a custom virtualenv to install Canaille.
Note that you should customize the EXTRAS
packages, depending on your needs.
sudo mkdir --parents /opt/canaille
virtualenv /opt/canaille/env
. /opt/canaille/env/bin/activate
pip install "canaille[EXTRAS]"
canaille --version
Note
In the rest of the documentation, we consider that your virtualenv is activated,
and that the canaille
command is available.
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;
sqlite provides the dependencies to enable the SQLite backend;
postgresql provides the dependencies to enable the PostgreSQL backend;
mysql provides the dependencies to enable the MySQL backend;
sentry provides sentry integration to watch Canaille exceptions;
otp provides the dependencies to enable one-time password authentication;
sms provides the dependencies to enable sms sending;
server provides the dependencies to run a production server.
They can be installed with:
pip install "canaille[front,oidc,postgresql,server]"
Configure¶
The configuration documentation describe several ways to configure Canaille,
however the most common is to use a TOML configuration file and pass its path with the CONFIG
environment variable.
A configuration file with default values can be initialized with the config dump command.
export CONFIG=/path/to/my/config.toml
canaille config dump
You can then edit your configuration file and tune its values. Have a look at the reference to know the exhaustive list of available parameters.
Note
In the rest of the documentation, we consider that your Canaille instance is configured by one of the available methods (either with a CONFIG
environment var, either with .env
files etc.).
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.
canaille install
Check¶
After a manual installation, you can test the network parameters in your configuration file using the check command.
It will attempt to connect your SMTP server
, or your SMPP server
if defined.
canaille config check
Create the first user¶
Once canaille is installed, soon enough you will need to add users. To create your first user you can use the canaille create CLI.
canaille create user \
--user-name admin \
--password admin \
--emails admin@mydomain.example \
--given-name George \
--family-name Abitbol