Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/openfun/ralph
:gear: Ralph, the ultimate Learning Record Store (and more!) for your learning analytics
https://github.com/openfun/ralph
analytics cli data-stream docker elasticsearch fastapi gelf k8s learning-analytics lrs pydantic python stream-processing xapi
Last synced: 7 days ago
JSON representation
:gear: Ralph, the ultimate Learning Record Store (and more!) for your learning analytics
- Host: GitHub
- URL: https://github.com/openfun/ralph
- Owner: openfun
- License: mit
- Created: 2020-02-05T14:31:27.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T17:06:40.000Z (6 months ago)
- Last Synced: 2024-04-12T22:19:33.671Z (6 months ago)
- Topics: analytics, cli, data-stream, docker, elasticsearch, fastapi, gelf, k8s, learning-analytics, lrs, pydantic, python, stream-processing, xapi
- Language: Python
- Homepage: https://openfun.github.io/ralph/
- Size: 13.2 MB
- Stars: 31
- Watchers: 10
- Forks: 14
- Open Issues: 45
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
Ralph, the ultimate Learning Record Store (and more!) for your learning analytics
---
**Documentation**: [https://openfun.github.io/ralph](https://openfun.github.io/ralph)
**Source Code**: [https://github.com/openfun/ralph](https://github.com/openfun/ralph)
---
Ralph is a toolbox for your learning analytics, it can be used as a:
- **[LRS](https://en.wikipedia.org/wiki/Learning_Record_Store)**, a HTTP API server to collect xAPI statements (learning events), following the [ADL LRS standard](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#partthree)
- **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](https://adlnet.gov/projects/xapi/), or
[openedx](https://docs.openedx.org/en/latest/developers/references/internal_data_formats/tracking_logs/index) html
## ⚡️ Quick start guide: Run the LRS server
> Preliminary notes:
>
> 1. [`curl`](https://curl.se), [`jq`](https://stedolan.github.io/jq/) and
> [`docker compose`](https://docs.docker.com/compose/) are required to run
> some commands of this tutorial. Make sure they are installed first.
>
> 2. 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:
```bash
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:
```bash
make status # This is an alias for: docker compose ps
```
You may now start the LRS server using:
```bash
make run
```
The server should be up and running at
[http://localhost:8100](http://localhost:8100). You can check its status using
the heartbeat probe:
```bash
curl http://localhost:8100/__heartbeat__
```
The expected answer should be:
```json
{"database":"ok"}
```
If the database status is satisfying, you are now ready to send xAPI statements
to the LRS:
```bash
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](https://github.com/openfun/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:
```bash
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](https://hub.docker.com/repository/docker/fundocker/ralph). If
[Docker](https://docs.docker.com/get-docker/) is installed on your machine, it
can be pulled from DockerHub:
```bash
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.):
```bash
# 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:
```bash
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_:
```bash
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](https://github.com/openfun/ralph/blob/main/UPGRADE.md) 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](https://handbook.openfun.fr).
## Useful commands
You can explore all available rules using:
```bash
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](./LICENSE.md)).