Copyright (c) 2024 University Claude Bernard Lyon 1 / LIRIS, CNRS
The source code of the **MOBILES Recommender System** is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/).
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. To view a copy of this license, visit [https://creativecommons.org/licenses/by-nc-sa/4.0/](https://creativecommons.org/licenses/by-nc-sa/4.0/).
## Permissions
You are free to:
-**Share** — copy and redistribute the material in any medium or format.
-**Adapt** — remix, transform, and build upon the material for any purpose, even commercially.
-**Adapt** — remix, transform, and build upon the material, for non-commercial purposes only.
This license is acceptable for Free Cultural Works.
## Conditions
Under the following terms:
-**Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
-**NonCommercial** — You may not use the material for commercial purposes.
-**ShareAlike** — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
## Notices
-**No additional restrictions** — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
- For more detailed information, you may visit the Creative Commons website at [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/).
- For more detailed information, you may visit the Creative Commons website at [https://creativecommons.org/licenses/by-nc-sa/4.0/](https://creativecommons.org/licenses/by-nc-sa/4.0/).
## Disclaimer
The software is provided "as-is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.
## Example Usage
To attribute this work, you should use the following:
"MOBILES Recommender System" by LIRIS, CNRS, licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/).
"MOBILES" by University Claude Bernard Lyon 1 / LIRIS, CNRS, licensed under CC BY-NC-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-nc-sa/4.0/](https://creativecommons.org/licenses/by-nc-sa/4.0/).
## Instructions
If you create derivatives of this software, you should also include the following notice:
"This work is a derivative of 'MOBILES Recommender System' by LIRIS, CNRS, used under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)."
\ No newline at end of file
"This work is a derivative of 'MOBILES' by University Claude Bernard Lyon 1 / LIRIS, CNRS, used under CC BY-NC-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-nc-sa/4.0/](https://creativecommons.org/licenses/by-nc-sa/4.0/)."
The **MOBILES RecSys** is an autonomous recommendation system designed to enhance the user experience of international students using the **MOBILES** app. By providing personalized recommendations based on user behavior, interactions, and preferences, the system leverages advanced data analytics and geolocated data. **MOBILES RecSys** integrates seamlessly with the MOBILES app, which allows users to explore the city, collect geolocated data, and share annotations, enriching their urban experiences. This system uses behavioral indicators to generate personalized recommendations that are tailored to each user's unique interactions with the city.
## Features
## Getting started
-**Personalized Recommendations**: The system generates recommendations based on user interactions and behavioral indicators, tailoring suggestions for each user profile.
-**Geolocated Annotations**: Users can create detailed, geolocated annotations, enhancing their urban exploration experience and sharing personal insights about their environment.
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
-**Behavioral Indicators**: These indicators are calculated in four main stages: Onboarding and Integration, Active Usage Support, Quality Improvement, and Urban Discovery.
-**Containerized Architecture**: MOBILES RecSys is deployed using **Docker** and **Docker Compose**, which ensures optimal resource management and simplifies deployment.
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
-**Data Storage and Processing**:
-**MariaDB** is used for user data storage.
-**kTBS** records digital traces of user interactions.
-**Logstash** processes user data and interaction logs, which are then indexed into **Elasticsearch**.
## Add your files
-**Dashboard**: A user-friendly interface, developed in **Ruby**, allows users to configure and automate system actions such as data retrieval, indicator calculation, recommendation generation, and notification sending.
-[ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-[ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
## Installation
### 1. Modify Configuration Files
Update the `.env` file with your environment-specific variables:
```plaintext
ELASTIC_VERSION=8.11.3
ELASTIC_PASSWORD='mobilespassword'
LOGSTASH_INTERNAL_PASSWORD='mobilespassword'
MONITORING_INTERNAL_PASSWORD=''
BEATS_SYSTEM_PASSWORD=''
MYSQL_USER='mobiles'
MYSQL_PASSWORD='mobilespassword'
MYSQL_ROOT_PASSWORD='mobilespassword'
MYSQL_DB='mobiles'
KTBS_USER='mobiles'
KTBS_PASSWORD='mobilespassword'
KTBS_URL='https://KTBS_URL/tracesmobiles/@obsels'
```
### 2. Modify Configuration for Recommendation System
Update the `rs/config/settings.py` file to reflect the correct database and Elasticsearch configurations, ensuring that the system connects to the right services.
### 3. Start the Setup and Run Containers
First, run the setup to initialize the necessary services:
-[ ] [Set up project integrations](https://gitlab.liris.cnrs.fr/msadallah/mobilesrs/-/settings/integrations)
Once the application is running, open your web browser and go to [http://localhost:8080](http://localhost:8080) to access the **MOBILES RecSys** dashboard. The dashboard provides a user interface to manage system settings, automate actions like data retrieval, indicator calculation, recommendation generation, and notification dispatch.
## Collaborate with your team
## Project Structure
-[ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-[ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-[ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
setup/: Contains setup scripts and service initialization configurations.
elasticsearch/: Configuration for the Elasticsearch service.
logstash/: Configuration and pipelines for Logstash.
db/: Database initialization scripts.
rs/: Source code for the recommendation system and Flask-based web application.
config/: Configuration files for application settings.
```
## Test and Deploy
## Technical Details
Use the built-in continuous integration in GitLab.
### Setup
-[ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-[ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-[ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-[ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-[ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
-**Initialization**: The `setup/` directory includes scripts for initializing the necessary services (Elasticsearch, Logstash, MariaDB, kTBS). These scripts configure and set up the environment, ensuring that all required services are in place before starting the application.
***
### Elasticsearch
# Editing this README
-**Search and Indexing**: **Elasticsearch** is used for storing, searching, and indexing user interaction data. It enables efficient retrieval of logs and other data necessary for generating accurate and personalized recommendations.
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
### Logstash
## Suggestions for a good README
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
-**Data Processing**: **Logstash** plays a crucial role in the system's ETL (Extract, Transform, Load) pipeline. It processes interaction logs, user data, and other inputs, transforming them into a format suitable for storage in **Elasticsearch**. It extracts data from **MariaDB** and **kTBS**, processes it, and sends it to Elasticsearch for indexing.
## Name
Choose a self-explaining name for your project.
### MariaDB
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
-**Database Storage**: All user data, including collected logs and interactions, is stored in a **MariaDB** database. MariaDB serves as the persistent storage solution for user information and application interactions, ensuring that data is available for analysis and recommendation generation.
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
### kTBS
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
-**Trace Management**: The **kTBS** instance records digital traces of user interactions within the app. These traces are crucial for understanding user behavior and usage patterns. **Logstash** processes the data from **kTBS**, transforming it into actionable insights that contribute to the recommendation system.
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
### Recommendation System (rs)
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
-**Python and Flask**: The recommendation system is implemented in **Python** and utilizes **Flask** to create a web application. This system calculates behavioral indicators based on user interactions and generates personalized recommendations based on these indicators.
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
-**Configuration**: The `rs/config/settings.py` file contains all the necessary configurations for connecting to external services such as the database and Elasticsearch. It also defines settings for recommendation algorithms and data processing.
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
### Dashboard
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
-**User Interface**: The **MOBILES RecSys** dashboard is developed in **Ruby** and provides a rich, interactive interface for managing system configurations. Users can configure the behavior of the system, automate tasks such as data retrieval, manage recommendation generation, and send notifications.
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
## Running the System
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
To run the system, follow these steps:
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
1.**Modify Configuration Files**: Ensure that the `.env` file and `rs/config/settings.py` are correctly updated with environment variables and configurations.
2.**Run Setup**: Initialize necessary services with the following command:
```bash
docker-compose up setup
```
3.**Start the Application**: After setup, start the application in detached mode:
```bash
docker-compose up -d
```
4.**Access the Dashboard**: Open your browser and navigate to [http://localhost:8080](http://localhost:8080) to access the **MOBILES RecSys** dashboard, where you can manage the system and monitor the recommendation processes.
## Contribution
Contributions are welcome! Please reach out to us if you are interested in contributing to this project.
## License
For open source projects, say how it is licensed.
This project is licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/).
## Acknowledgements
This project is supported by the ANR under grant number ANR-20-CE38-0009. We thank the members of the partner laboratories for their contributions to the project's conception and ideas.
### Contact
- Madjid Sadallah
- Raphaël Benedetto
---
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
If you have any questions or need assistance, please contact the project members via their respective emails.
