===== merou

.. image:: https://travis-ci.org/dropbox/merou.svg?branch=master :alt: Build Status :target: https://travis-ci.org/dropbox/merou

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :alt: Code Style: Black :target: https://github.com/ambv/black

Description

Merou is an application to allow users to create and manage memberships to their own groups. It requires Python 3.7 or later.

Note: We renamed the project to avoid a namespace conflict <https://github.com/Internet2/grouper>_, but it isn't reflected in the codebase yet.

Installation

Standard Python package installation instructions apply. You will need Python 3 and development headers for MySQL.

On Debian-based systems:

.. code:: bash

apt-get install libmysqlclient-dev libpython3-dev libcurl4-openssl-dev libssl-dev python3-pip
pip3 install -e git+https://github.com/dropbox/merou#egg=grouper

Next you need to configure grouper to find a SQL-style backing database and stand up processes to serve the read-write web UI and read-only programmatic API. There's an sample configuration file, suitable for local development and testing, in config/dev.yaml.

Running a Test instance

Grouper runs behind a reverse proxy that handles authentication and so expects a valid, authenticated, user account. I've included a test proxy for running on development instances.

Creating a development instance:

.. code:: bash

export PYTHONPATH=$(pwd)
export GROUPER_SETTINGS=$(pwd)/config/dev.yaml

# Setup the database.
bin/grouper-ctl sync_db

## You can either run all the various servers and the reverse-proxy
## via a helper script:
tools/run-dev --user [email protected]

## Or separately:
# Run the development reverse proxy
bin/grouper-ctl -vv user_proxy [email protected]

# Run the frontend server
bin/grouper-fe -vv

# Run the graph/api server
bin/grouper-api -vv

Setting up the first groups and permissions

In order to bootstrap your new Grouper environment, you will want to create a user for yourself and add it to the grouper-administrators group.

.. code:: bash

export PYTHONPATH=$(pwd)
export GROUPER_SETTINGS=$(pwd)/config/dev.yaml

bin/grouper-ctl -vv\
    user create [email protected]

# Give the user administrative access to the Grouper instance
bin/grouper-ctl -vv \
    group add_member --owner grouper-administrators [email protected]

Running the tests

Some tests require a recent (>= 2.31) version of chromium-driver, which can be installed via apt or Homebrew:

.. code:: bash

apt install chromium-driver

(This may be called chromium-chromedriver in older versions.) Once chromium-driver is installed, the tests can be run using pytest:

.. code:: bash

pip install -r requirements.txt
pip install -r requirements-dev.txt
pytest
flake8
mypy .

If you see test failures and suspect incompatible library versions (e.g., an existing tornado install at a different major release than that in our requirements.txt), then you can try using a virtual environment.

.. code:: bash

$ virtualenv ~/merou-venv -p /usr/bin/python3
$ source ~/merou-venv/bin/activate
(merou-venv) $ pip install -r requirements.txt
(merou-venv) $ pip install -r requirements-dev.txt
(merou-venv) $ pytest
(merou-venv) $ deactivate
$

All Merou code is formatted with black, which is installed by the requirements-dev.txt requirements file for Python 3. After installation, you can reformat all source code with:

.. code:: bash

black .

All new code must be formatted with the version of black indicated in requirements-dev.txt in order to pass Travis CI tests.