Contributions

Contributions are welcome!

The repository is hosted at gitlab.com/yaal/canaille.

Discuss

If you want to implement a feature or a bugfix, please start by discussing it with us on the bugtracker or the matrix room.

Development environment

You can either run the demo locally or with docker. After having launched the demo you have access to several services:

The canaille server has some default users:

  • A regular user which login and password are user;

  • A moderator user which login and password are moderator;

  • An admin user which admin and password are admin;

  • A new user which login is james. This user has no password yet, and his first attempt to log-in would result in sending a password initialization email (if a smtp server is configured).

Backends

Canaille comes with several backends:

  • a lightweight test purpose memory backend

  • a sql backend, based on sqlalchemy

  • a production-ready LDAP backend

Docker environment

If you want to develop with docker, your browser needs to be able to reach the canaille container. The docker-compose file exposes the right ports, but front requests are from outside the docker network: the canaille url that makes sense for docker, points nowhere from your browser. As exposed ports are on localhost, you need to tell your computer that canaille url means localhost.

To do that, you can add the following line to your /etc/hosts:

127.0.0.1   canaille

To launch containers, use:

cd demo
# To run the demo with the sql backend:
docker compose up

# To run the demo with the memory backend:
docker compose --file docker-compose-memory.yml up

# To run the demo with the LDAP backend:
docker compose --file docker-compose-ldap.yml up

Local environment

# To run the demo with the sql backend:
./demo/run.sh

# To run the demo with the memory backend:
./demo/run.sh --backend memory

# To run the demo with the LDAP backend:
./demo/run.sh --backend ldap

Note

If you want to run the demo locally with the LDAP backend, you need to have OpenLDAP installed on your system. It is generally shipped under the slapd or openldap package name.

Warning

On Debian or Ubuntu systems, the OpenLDAP slapd binary usage might be restricted by apparmor, and thus makes the tests and the demo fail. This can be mitigated by removing apparmor restrictions on slapd.

sudo apt install --yes apparmor-utils
sudo aa-complain /usr/sbin/slapd

Populate the database

The demo database comes populated with some random users and groups. If you need more, you can generate users and groups with the populate command:

# If using docker:
docker compose exec canaille env CONFIG=conf-docker/canaille-ldap.toml poetry run canaille populate --nb 100 users  # or docker-compose

# If running in local environment
env CONFIG=conf/canaille-ldap.toml poetry run canaille populate  --nb 100 users

Adapt to use either the ldap or the sql configuration file. Note that this will not work with the memory backend.

Unit tests

To run the tests, you just can run poetry run pytest and/or tox to test all the supported python environments. Everything must be green before patches get merged.

To test a specific backend you can pass --backend memory, --backend sql or --backend ldap to pytest and tox.

The test coverage is 100%, patches won’t be accepted if not entirely covered. You can check the test coverage with poetry run pytest --cov --cov-report=html or tox -e coverage -- --cov-report=html. You can check the HTML coverage report in the newly created htmlcov directory.

Code style

We use ruff along with other tools to format our code. Please run tox -e style on your patches before submitting them. In order to perform a style check and correction at each commit you can use our pre-commit configuration with pre-commit install.

Front

The interface is built upon the Fomantic UI CSS framework. The dynamical parts of the interface use htmx.

  • Using Javascript in the interface is tolerated, but the whole website MUST be accessible for browsers without Javascript support, and without any feature loss.

  • Because of Fomantic UI we have a dependency to jQuery, however new contributions should not depend on jQuery at all. See the related issue.

Translations

Translations are done with Weblate.

The following commands are there as documentation, only the message extraction is needed for contributors. All the other steps are automatically done with Weblate.

Message extraction

After you have edited translatable strings, you should extract the messages with:

pybabel extract --mapping-file pyproject.toml --copyright-holder="Yaal Coop" --output-file canaille/translations/messages.pot canaille

Language addition

You can add a new language manually with the following command, however this should not be needed as Weblate takes car of this:

pybabel init --input-file canaille/translations/messages.pot --output-dir canaille/translations --locale <LANG>

Catalog update

You can update the catalogs with the following command, however this should not be needed as Weblate automatically update language catalogs when it detects new strings or when someone translate some existing strings. Weblate pushes happen every 24h.

pybabel update --input-file canaille/translations/messages.pot --output-dir canaille/translations --ignore-obsolete --no-fuzzy-matching --update-header-comment

Catalog compilation

You can compile the catalogs with the following command, however this should not be needed as catalogs are automatically compiled before running the unit tests, before launching the demo and before compiling the Canaille python package:

pybabel compile --directory canaille/translations --statistics

Documentation

The documentation is generated when the tests run:

tox -e doc

You can also run sphinx by hand, that should be faster since it avoids the tox environment initialization:

sphinx-build doc build/sphinx/html

The generated documentation is located at build/sphinx/html.

Publish a new release

  1. Check that dependencies are up to date with poetry show --outdated --with dev,doc,demo and update dependencies accordingly in separated commits.

  2. Check that tests are still green for every supported python version, and that coverage is still at 100%, by running tox

  3. Check that the demo environments are still working

  4. Check that the Release notes section is correctly filled up

  5. Increase the version number in pyproject.toml

  6. Commit with git commit

  7. Publish with poetry publish --build

  8. Tag you commit with git tag XX.YY.ZZ

  9. Push the release commit and the new tag on the repository with git push --tags