# Ralph
[](https://discord.gg/vYx6YWxJCS)
Ralph is a toolbox for your learning analytics, it can be used as a:
- **library**, to fetch learning events from various backends, (de)serialize or
convert them from 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)
- **command-line interface** (CLI), to build data pipelines the UNIX-way™️,
- **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).
## Quick start guide
### Testing the LRS server with Docker compose
> 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:
```
$ 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:
```
$ make run
```
The server should be up and running at
[http://localhost:8100](http://localhost:8100). You can check its status using
the hearbeat probe:
```
$ 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:
```
$ curl -sL https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \
gunzip | \
head -n 100 | \
sed "s/@timestamp/timestamp/g" | \
jq -s . | \
curl -Lk \
--user ralph:secret \
-X POST \
-H "Content-Type: application/json" \
http://localhost:8100/xAPI/statements/ -d @-
```
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:
```
$ 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.
### Testing the CLI (Docker)
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:
```
$ docker run --pull always --rm fundocker/ralph:latest ralph --help
```
### Testing the CLI (Python)
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.):
```sh
# Install the full package
$ pip install \
ralph-malph[backend-es,backend-ldp,backend-mongo,backend-swift,backend-ws,cli,lrs]
# 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.
## Documentation
We try our best to maintain an up-to-date reference documentation for this
project. If you intend to install, test or contribute to ralph, we invite you
to read this [documentation](https://openfun.github.io/ralph) and give us
feedback if some parts are unclear or your use case is not (or poorly) covered.
## 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 recommandations from our
[handbook](https://handbook.openfun.fr).
## License
This work is released under the MIT License (see [LICENSE](./LICENSE.md)).
Raw data
{
"_id": null,
"home_page": "https://openfun.github.io/ralph/",
"name": "thibaultlebrun-ralph-malph",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Open edX,Analytics,xAPI,LRS",
"author": "Open FUN (France Universite Numerique)",
"author_email": "fun.dev@fun-mooc.fr",
"download_url": "https://files.pythonhosted.org/packages/8f/48/bed11cb2c1e20ce7b284d78001de9fb7cbd60e9ae8686fdb977d1004258d/thibaultlebrun-ralph-malph-3.6.0.tar.gz",
"platform": null,
"description": "# Ralph\n\n[](https://discord.gg/vYx6YWxJCS)\n\nRalph is a toolbox for your learning analytics, it can be used as a:\n\n- **library**, to fetch learning events from various backends, (de)serialize or\n convert them from various standard formats such as\n [xAPI](https://adlnet.gov/projects/xapi/), or\n [openedx](https://docs.openedx.org/en/latest/developers/references/internal_data_formats/tracking_logs/index.html)\n- **command-line interface** (CLI), to build data pipelines the UNIX-way\u2122\ufe0f,\n- **HTTP API server**, to collect xAPI statements (learning events)\n following the [ADL LRS\n standard](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#partthree).\n\n## Quick start guide\n\n### Testing the LRS server with Docker compose\n\n\n> Preliminary notes:\n>\n> 1. [`curl`](https://curl.se), [`jq`](https://stedolan.github.io/jq/) and\n> [`docker compose`](https://docs.docker.com/compose/) are required to run\n> some commands of this tutorial. Make sure they are installed first.\n>\n> 2. In order to run the Elasticsearch backend locally on GNU/Linux operating\n> systems, ensure that your virtual memory limits are not too low and\n> increase them (temporally) if needed by typing this command from your\n> terminal (as `root` or using `sudo`): `sysctl -w vm.max_map_count=262144`\n>\n> Reference:\n> https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html\n\nTo bootstrap a test environment on your machine, clone this project first and\nrun the `bootstrap` Makefile target:\n\n```\n$ make bootstrap\n```\n\nThis command will create required `.env` file (you may want to edit it for your\ntest environment), build the Ralph's Docker image and start a single node\nElasticsearch cluster _via_ Docker compose.\n\nYou can check the `elasticsearch` service status using the `status` helper:\n\n```bash\n$ make status\n\n# This is an alias for:\n$ docker compose ps\n```\n\nYou may now start the LRS server using:\n\n```\n$ make run\n```\n\nThe server should be up and running at\n[http://localhost:8100](http://localhost:8100). You can check its status using\nthe hearbeat probe:\n\n```\n$ curl http://localhost:8100/__heartbeat__\n```\n\nThe expected answer should be:\n\n```json\n{\"database\":\"ok\"}\n```\n\nIf the database status is satisfying, you are now ready to send xAPI statements\nto the LRS:\n\n```\n$ curl -sL https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \\\n gunzip | \\\n head -n 100 | \\\n sed \"s/@timestamp/timestamp/g\" | \\\n jq -s . | \\\n curl -Lk \\\n --user ralph:secret \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n http://localhost:8100/xAPI/statements/ -d @-\n```\n\nThe command above fetches one hundred (100) example xAPI statements from our\n[Potsie](https://github.com/openfun/potsie) project and sends them to the LRS\nusing `curl`.\n\nYou can get them back from the LRS using `curl` to query the\n`/xAPI/statements/` endpoint:\n\n```\n$ curl -s \\\n --user ralph:secret \\\n -H \"Content-Type: application/json\" \\\n http://localhost:8100/xAPI/statements/ \\ |\n jq\n```\n\n> Note that using `jq` is optional in this case, it is used to improve response\n> readability. It is not required to install it to run this snippet.\n\n\n### Testing the CLI (Docker)\n\nRalph is distributed as a [Docker\nimage](https://hub.docker.com/repository/docker/fundocker/ralph). If\n[Docker](https://docs.docker.com/get-docker/) is installed on your machine, it\ncan be pulled from DockerHub:\n\n```\n$ docker run --pull always --rm fundocker/ralph:latest ralph --help\n```\n\n### Testing the CLI (Python)\n\nRalph is distributed as a standard python package; it can be installed _via_\n`pip` or any other python package manager (_e.g_ Poetry, Pipenv, etc.):\n\n```sh\n# Install the full package\n$ pip install \\\n ralph-malph[backend-es,backend-ldp,backend-mongo,backend-swift,backend-ws,cli,lrs]\n\n# Install only the core package (library usage without backends, CLI and LRS)\n$ pip install ralph-malph\n```\n\nIf you installed the full package (including the CLI, LRS and supported\nbackends), the `ralph` command should be available in your `PATH`. Try to\ninvoke the program usage thanks to the `--help` flag:\n\n```\n$ ralph --help\n```\n\nYou should see a list of available commands and global flags for `ralph`. Note\nthat each command has its own usage that can be invoked _via_:\n\n```\n$ ralph COMMAND --help\n```\n\n> You should substitute `COMMAND` by the target command, _e.g._ `list`, to see\n> its usage.\n\n## Documentation\n\nWe try our best to maintain an up-to-date reference documentation for this\nproject. If you intend to install, test or contribute to ralph, we invite you\nto read this [documentation](https://openfun.github.io/ralph) and give us\nfeedback if some parts are unclear or your use case is not (or poorly) covered.\n\n## Contributing\n\nThis project is intended to be community-driven, so please, do not hesitate to\nget in touch if you have any question related to our implementation or design\ndecisions.\n\nWe try to raise our code quality standards and expect contributors to follow\nthe recommandations from our\n[handbook](https://handbook.openfun.fr).\n\n## License\n\nThis work is released under the MIT License (see [LICENSE](./LICENSE.md)).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The ultimate toolbox for your learning analytics",
"version": "3.6.0",
"project_urls": {
"Homepage": "https://openfun.github.io/ralph/"
},
"split_keywords": [
"open edx",
"analytics",
"xapi",
"lrs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34314f8bcd1bf6d1998d4205a59da0861d17cb696334c5cc18adac08d014cde5",
"md5": "4b4def772c896a644903346a9ceaaede",
"sha256": "ba2668de51218b7db083eece5a17e5bc2b3dc5de312faa9445135ff478b8b135"
},
"downloads": -1,
"filename": "thibaultlebrun_ralph_malph-3.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4b4def772c896a644903346a9ceaaede",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 105878,
"upload_time": "2023-06-01T23:17:25",
"upload_time_iso_8601": "2023-06-01T23:17:25.101683Z",
"url": "https://files.pythonhosted.org/packages/34/31/4f8bcd1bf6d1998d4205a59da0861d17cb696334c5cc18adac08d014cde5/thibaultlebrun_ralph_malph-3.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f48bed11cb2c1e20ce7b284d78001de9fb7cbd60e9ae8686fdb977d1004258d",
"md5": "e38dbd5986180c13606cfea4e159c3a2",
"sha256": "749ef3ca9fa1fccb7ad56eca3ad9fb33ac366be6960c30a5ec8bd262a7a65c30"
},
"downloads": -1,
"filename": "thibaultlebrun-ralph-malph-3.6.0.tar.gz",
"has_sig": false,
"md5_digest": "e38dbd5986180c13606cfea4e159c3a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 76214,
"upload_time": "2023-06-01T23:17:27",
"upload_time_iso_8601": "2023-06-01T23:17:27.784241Z",
"url": "https://files.pythonhosted.org/packages/8f/48/bed11cb2c1e20ce7b284d78001de9fb7cbd60e9ae8686fdb977d1004258d/thibaultlebrun-ralph-malph-3.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-01 23:17:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "thibaultlebrun-ralph-malph"
}
JSON