ralph-malph 5.0.1

Description:

ralphmalph 5.0.1

Ralph, the ultimate Learning Record Store (and more!) for your learning analytics






















Documentation: https://openfun.github.io/ralph
Source Code: https://github.com/openfun/ralph

Ralph is a toolbox for your learning analytics, it can be used as a:

LRS, a HTTP API server to collect xAPI statements (learning events), following the ADL LRS standard
command-line interface (CLI), to build data pipelines the UNIX-way™️,
library, to fetch learning events from various backends, (de)serialize or
convert them from and to various standard formats such as
xAPI, or
openedx html

⚡️ Quick start guide: Run the LRS server

Preliminary notes:


curl, jq and
docker compose are required to run
some commands of this tutorial. Make sure they are installed first.


In order to run the Elasticsearch backend locally on GNU/Linux operating
systems, ensure that your virtual memory limits are not too low and
increase them (temporally) if needed by typing this command from your
terminal (as root or using sudo): sysctl -w vm.max_map_count=262144


Reference:
https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html

To bootstrap a test environment on your machine, clone this project first and
run the bootstrap Makefile target:
make bootstrap

This command will create required .env file (you may want to edit it for your
test environment), build the Ralph's Docker image and start a single node
Elasticsearch cluster via Docker compose.
You can check the elasticsearch service status using the status helper:
make status # This is an alias for: docker compose ps

You may now start the LRS server using:
make run

The server should be up and running at
http://localhost:8100. You can check its status using
the heartbeat probe:
curl http://localhost:8100/__heartbeat__

The expected answer should be:
{"database":"ok"}

If the database status is satisfying, you are now ready to send xAPI statements
to the LRS:
gunzip -c data/statements.json.gz | \
head -n 100 | \
jq -s . | \
curl -Lk \
--user ralph:secret \
-X POST \
-H "Content-Type: application/json" \
-d @- \
http://localhost:8100/xAPI/statements/

The command above fetches one hundred (100) example xAPI statements from our
Potsie project and sends them to the LRS
using curl.
You can get them back from the LRS using curl to query the
/xAPI/statements/ endpoint:
curl -s \
--user ralph:secret \
-H "Content-Type: application/json" \
http://localhost:8100/xAPI/statements/ \ |
jq


Note that using jq is optional in this case, it is used to improve response
readability. It is not required to install it to run this snippet.

⚡️ Quick start guide: Manipulate data with the CLI
With the Docker image
Ralph is distributed as a Docker
image. If
Docker is installed on your machine, it
can be pulled from DockerHub:
docker run --pull always --rm fundocker/ralph:latest ralph --help

With the Python package
Ralph is distributed as a standard python package; it can be installed via
pip or any other python package manager (e.g. Poetry, Pipenv, etc.):
# Install the full package
pip install \
ralph-malph[full]

# Install only the core package (library usage without backends, CLI and LRS)
pip install ralph-malph

If you installed the full package (including the CLI, LRS and supported
backends), the ralph command should be available in your PATH. Try to
invoke the program usage thanks to the --help flag:
ralph --help

You should see a list of available commands and global flags for ralph. Note
that each command has its own usage that can be invoked via:
ralph COMMAND --help


You should substitute COMMAND by the target command, e.g. list, to see
its usage.

Migrating
Some major version changes require updating persistence layers. Check out the migration guide for more information.
Contributing
This project is intended to be community-driven, so please, do not hesitate to
get in touch if you have any question related to our implementation or design
decisions.
We try to raise our code quality standards and expect contributors to follow
the recommendations from our
handbook.
Useful commands
You can explore all available rules using:
make help

but here are some of them:

Bootstrap the project: make bootstrap
Run tests: make test
Run all linters: make lint
If you add new dependencies to the project, you will have to rebuild the Docker
image (and the development environment): make down && make bootstrap

License
This work is released under the MIT License (see LICENSE).