From 5fc4ad9ac94f9f54697ac1f33a3c42e0db06ed28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89loi=20Rivard?= Date: Sun, 12 Mar 2023 00:45:57 +0100 Subject: [PATCH] Improved the 'CONTRIBUTING' documentation --- CONTRIBUTING.rst | 50 ++++++++++++++++++++++++++++++++++++------------ demo/README.md | 48 +--------------------------------------------- demo/run.sh | 5 ++++- 3 files changed, 43 insertions(+), 60 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3ad9c349..60c9da09 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -8,11 +8,40 @@ The repository is hosted at `gitlab.com/yaal/canaille `_ +- A dummy client at `localhost:5001 `_ +- Another dummy client at `localhost:5002 `_ + +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 configurated). + + +Docker environment +~~~~~~~~~~~~~~~~~~ + +If you want to develop with docker, use: + .. code-block:: console - python3 setup.py compile_catalog - cd demo - ./run.sh # or `docker-compose up` to run it with docker + cd demo && docker-compose up + +Local environment +~~~~~~~~~~~~~~~~~ + +If you want to develop locally, use: + +.. code-block:: console + + ./demo/run.sh .. warning :: @@ -25,17 +54,14 @@ Development environment sudo apt install --yes apparmor-utils sudo aa-complain /usr/sbin/slapd -Then you have access to: +Populate the database +~~~~~~~~~~~~~~~~~~~~~ -- A canaille server at `localhost:5000 `_ -- A dummy client at `localhost:5001 `_ -- Another dummy client at `localhost:5002 `_ +You can populate the database with randomly generated users and groups with the ``populate`` command: -The canaille server has some default users: +.. code-block:: console -- 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**. + env CONFIG=conf/canaille.toml poetry run canaille populate Unit tests ---------- @@ -81,4 +107,4 @@ The documentation is generated when the tests run: tox -e doc -The generated documentation is in `./build/sphinx/html/` directory. +The generated documentation is located at `./build/sphinx/html`. diff --git a/demo/README.md b/demo/README.md index 904b5ceb..296acd13 100644 --- a/demo/README.md +++ b/demo/README.md @@ -4,50 +4,4 @@ To check out how canaille looks like, or to start contributions, just run the de - with `docker-compose up` to install and run it in preconfigured docker containers - or with `./run.sh` to install it natively in a virtual environment and run it locally! -# Prerequisites for native demo installation - -You need to have `OpenLDAP` somewhere in your system. - -You need to install it with your distro packages *(for instance `sudo apt install slapd -ldap-utils` with Ubuntu)*. It is not required to launch the system ldap service. - -Canaille depends on [python-ldap](https://github.com/python-ldap/python-ldap), and this package needs -some headers to be installed on your system to be built. For instance on Ubuntu you can install this: -`sudo apt install libsasl2-dev python-dev libldap2-dev libssl-dev`. More info -[on this SO ticket](https://stackoverflow.com/questions/4768446/i-cant-install-python-ldap). - -## Apparmor - -On Ubuntu systems, apparmor prevents *slapd* from accessing files that are not in the standard -OpenLDAP installation. This may result in canaille being impossible to launch. To fix this you -can pass slapd in complain mode: - -```bash -sudo apt install --yes apparmor-utils -sudo aa-complain /usr/sbin/slapd -``` - -# Run the demo - -Then you have access to: - -- A canaille server at http://localhost:5000 -- A dummy client at http://localhost:5001 -- Another dummy client at http://localhost:5002, for which consent is already granted for users - -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 login 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 configurated). - -# Populate the database - -You can populate the database with randomly generated users and groups with the ``populate`` command: - -```bash -env CONFIG=conf/canaille.toml poetry run canaille populate -``` +Please check the details on [the documentation](https://canaille.readthedocs.io/en/latest/contributing.html). diff --git a/demo/run.sh b/demo/run.sh index 73ec4b21..e62185c6 100755 --- a/demo/run.sh +++ b/demo/run.sh @@ -21,4 +21,7 @@ if ! type poetry > /dev/null 2>&1; then fi poetry install --with demo --without dev -env "PWD=$DIR" poetry run honcho start + +pushd "$DIR" > /dev/null 2>&1 || exit +env poetry run honcho start +popd || exit