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.

$ uvx "canaille[EXTRAS]" run

pip

$ virtualenv env
$ env/bin/pip install "canaille[EXTRAS]"
$ env/bin/canaille run

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 passcode authentication;
sms provides the dependencies to enable sms sending;
server provides the dependencies to run a production server.

They can be installed with:

$ uvx "canaille[front,oidc,postgresql,server]" run

pip

$ virtualenv env
$ env/bin/pip install "canaille[front,oidc,postgresql,server]"
$ env/bin/canaille run

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.

$ uvx "canaille[EXTRAS]" install

pip

$ canaille install

Check¶

After installation, you can test the network parameters in your configuration file using the config check command. It will attempt to connect your SMTP server, or your SMPP server if defined.

$ uvx "canaille[EXTRAS]" config check

pip

$ 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.

$ uvx "canaille[EXTRAS]" create user \
    --user-name admin \
    --password admin \
    --emails admin@mydomain.example \
    --given-name George \
    --family-name Abitbol \
    --formatted-name "George Abitbol"

pip

$ canaille create user \
    --user-name admin \
    --password admin \
    --emails admin@mydomain.example \
    --given-name George \
    --family-name Abitbol \
    --formatted-name "George Abitbol"