Readersourcing 2.0: An independent, third-party, no-profit, academic project aimed at quality rating of scholarly literature and scholars.

Info

This is the official repository of RS_Server, which is part of the Readersourcing 2.0 ecosystem. This repository is a Git Submodule of the main project, whose components can be found by taking advantage of the links below.

Useful Links

• Readersourcing 2.0 (Web Interface)
• Readersourcing 2.0 (GitHub)
• Original Article (Springer Link)
• Original Article (Zenodo)
• Technical Documentation (Zenodo)
• Technical Documentation (GitHub)
• RESTful API Interface
• Zenodo Record
• Docker Hub

Description

RS_Server is the server-side component which has the task of collecting and aggregating the ratings given by readers and using the Readersourcing-based models to compute quality scores for readers and publications. It is deployed together with an instance of RS_PDF. The server-side component exposes a RESTful API Interface and provides a stand-alone web interface to interact directly with the APIs.

Furthermore, there can be different browsers along with their end-users that communicate with the APIs of the server-side component by using an instance of RS_Rate, that is, a browser extension. Thus, every interaction between human readers and the APIs exposed by RS_Server can be carried out through clients installed on readers' browsers or by using the stand-alone web interface provided. These clients handle the registration and authentication of readers, the rating action and the download action of link-annotated publications.

Deploy

There are three main modalities that can be used to deploy a working instance of RS_Server in the development or production environment. The former environment must be used if there is the need to:

• add custom Readersourcing-based models;
• extend/modify the current implementation of RS_Server;
• simply to test it in a safe way.

In the following, three deployment modalities to obtain a working instance of RS_Server are described, along with their requirements. The first two modalities allow both to start RS_Server on the local machine allowing editing of its source code and to build a Docker image which can be deployed by local containers in a production-ready environment. The third modality allows for deploying RS_Server as a Heroku application.

Please, be sure to read the section dedicated to the environment variables, since RS_Server will not work properly without them.

Modality 1: Manual

This modality allows to manually download and initialize RS_Server's codebase in a local machine. This is the most demanding modality in terms of prerequisites since it assumes having a full and working installation of Ruby, JDK (Java Development Kit) and PostgreSQL. Despite that, it provides more flexibility.

Requirements

• Ruby == 2.7.8;
• JDK (Java Development Kit) == 11.0.19;
• PostgreSQL >= 11.2.

How To

Clone this repository and navigate to its main directory using a command line prompt (you should see app, bin, config, etc., folders with an ls or dir command) then type gem install bundler. This gem (dependency) provides a consistent environment for Ruby projects, as RS_Server, by tracking and installing the exact gems (dependencies) and versions needed.

To fetch all dependencies required by RS_Server, type bundle install and wait for the process to complete.

The next two commands are necessary only before the first startup of RS_Server because they will create and set up the database. Ensure that the PostgreSQL service is started and ready to accept connections on port 5432. Type rails db:create to create the database and rails db:migrate to create the required tables. Now, create a .env file as explained later and set the required environment variables. Optionally, you can type rails db:seed to seed some sample data in the database. After these commands, everything is ready to launch RS_Server in development or production mode.

To do that, just type cd bin to move inside bin directory and then type rails server -b 127.0.0.1 -p 3000 -e development with the proper values for -b, -p and -e options. If the sample values are used, RS_Server will be started and bound on the 127.0.0.1IP address with port 3000 and development environment. Every HTPP request, therefore, must be sent to the http://127.0.0.1:3000 address.

Quick Cheatsheet

• cd to main directory;
• gem install bundler;
• bundle install;
• rails db:create;
• rails db:migrate;
• rails db:seed (optional);
• create and populate the .env file;
• cd bin;
• rails server -b <your_ip_address> -p <your_port> -e development or rails server -b <your_ip_address> -p <your_port> -e production.

Modality 2: Manual (using Docker)

This modality allows to download and initialize RS_Server's codebase in a local machine using a faster and less frustrating approach based on Docker, despite being less flexible. Docker is a project which allows automating the deployment phase by distributing an image of an application inside a container.

An image is a lightweight, standalone, and executable package of software that includes everything needed to run an application: code, runtime, tools, libraries and settings. This means that there is no need to manually install the runtimes/libraries/dependencies needed to run an application since the Docker Engine will automatically initialize everything.

A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. Only a working installation of Docker Desktop CE (Community Edition) is required.

Requirements

• Docker Desktop CE (Community Edition).

How To

Clone this repository and move inside its main directory using a command line prompt. Now, type ls or dir; you should see a docker-compose.yml file and a Dockerfile. If you do not see them, please be sure to be in the main directory of the cloned repository.

Before proceeding, be sure that your Docker Engine is running, otherwise the following commands will not work. At this point, two different scenarios can take place.

Scenario 1: Deploy With Remote Images

If there is no need to edit the source code of RS_Server, the Docker Engine can fetch the dependencies required in the docker-compose.yml file and initialize the application. The dependencies specified in the file are an image of PostgreSQL for the database and one of RS_Server itself, released on the Docker Hub.

To do this, open the docker-compose.yml file and uncomment the following section and, additionally, comment out the remaining lines of code.

----------- SCENARIO 1: DEPLOY WITH REMOTE IMAGES ----------
...
----------- END OF SCENARIO 1: DEPLOY WITH REMOTE IMAGES ----------

Next, from the command line prompt, type docker-compose up and wait for the process to finish. Note that it may take several minutes. Once the Docker Engine completes the process, a container with a working instance of RS_Server will be started.

Optionally, you can type docker-compose run rails db:seed to seed some sample data in the database. RS_Server will be started and bound to the 0.0.0.0 IP address with port 3000 and the production environment. Every HTTP request, therefore, must be sent to the http://0.0.0.0:3000 address.

As can be seen, there is no need to manually start the server by specifying its IP address, port, and environment, or to create and migrate the database. The Docker Engine will perform that automatically. If you want to set a custom IP address or port or switch to the production environment, edit the command key inside the docker-compose.yml file.

To stop the container, simply type docker-compose down.

Scenario 2: Deploy With Local Build

If the source code of RS_Server has been edited, the application must be built from scratch by the Docker Engine according to the structure specified in the Dockerfile. After the image build phase, the Docker Engine can fetch the required dependencies outlined in the docker-compose.yml file and initialize RS_Server, as in the previous scenario.

To do this, open the docker-compose.yml file and uncomment the following section. Additionally, comment out the remaining lines of code in the file.

-----------  SCENARIO 2: DEPLOY WITH LOCAL BUILD ----------
...
----------- END OF SCENARIO 2: DEPLOY WITH LOCAL BUILD -----------

Next, from the command line prompt, type docker-compose up and wait for the process to finish. Note that it may take several minutes. Once the Docker Engine completes the process, a container with a working instance of RS_Server will be started and bound to the 0.0.0.0 IP address with port 3000 and the production environment. Therefore, every request must be sent to the http://0.0.0.0:3000 address.

Similar to the previous scenario, there is no need to manually start the server by specifying its IP address, port, and environment or to create and migrate the database. If you want to set a custom IP address or port or switch to the production environment, edit the command key inside the docker-compose.yml file.

To stop the container, simply type docker-compose down.

Quick Cheatsheet

• cd to main directory;
• create and populate the .env file;
• docker-compose up;
• docker-compose run rails db:seed (optionally);
• docker-compose down (to stop and undeploy).

Modality 3: Deploy on Heroku

Heroku is a cloud platform-as-a-service (PaaS) that simplifies building, deploying, and scaling web applications and services for developers. This deploy modality enables the use of its container registry for a Docker-based production-ready deployment of RS_Server on the platform, facilitated by the Heroku Command Line Interface (CLI). It's important to note that this modality can only be used with the production environment of the application.

Regarding the prerequisites for this modality, the developer must create an app on Heroku and then provision it with two addons: PostgreSQL for the database and one for mail-related functionalities, such as Twilio SendGrid. The Heroku tutorials provide a comprehensive overview of the platform. Additionally, a working installation of Docker Desktop CE (Community Edition) on the machine used for deployment is required.

Requirements

• Heroku account;
• Heroku application provisioned with:
• PostgreSQL addon;
• a mail-related addon such as Twilio SendGrid;
• Heroku CLI;
• Docker Desktop CE (Community Edition).

How To

Clone this repository and navigate to the main directory using a command line prompt. Now, type ls or dir. You should see a Dockerfile. If not, please ensure you are in the main directory of the cloned repository.

Before proceeding, make sure that your Docker Engine is running. Otherwise, the following commands will not work.

Log in using your credentials by typing heroku login. Next, log in to the Heroku container registry by typing heroku container:login.

To build and upload your instance of RS_Server using Docker, type heroku container:push web --app your-app-name. When the process completes, type heroku container:release web to make it publicly accessible.

Optionally, you can type heroku run rails db:seed to seed some sample data in the database, and heroku open to open the browser and be redirected to the homepage of the <your_app_name> application.

Similar to the previous modality, there is no need to manually start the server by specifying its IP address, port, and environment, or to create and migrate the database since Heroku (through the Docker Engine) will take care of that for you.

Quick Cheatsheet

• cd to main directory;
• heroku login;
• heroku container:login;
• heroku container:push web --app <your-app-name>;
• heroku container:release web --app <your-app-name>;
• heroku open --app <your-app-name> (optional);
• set the environment variables on your Heroku app.

Environment Variables

Regardless of the chosen deployment modality, the developer must provide values for (at least a portion of) the environment variables, as they cannot be checked into a repository due to safety reasons. In the following, each of these available variables is described along with an explanation of which deployment modality requires their usage.

Environment Variable	Description	Deploy Modality	Environment	Where To Set
SECRET_DEV_KEY	Private key used to encrypt strings in the development environment.	1 - 2	development	.env file
SECRET_PROD_KEY	Private key used to encrypt strings in the production environment.	1 - 2 - 3	production	.env file, Heroku app
POSTGRES_USER	Username the admin user of the database.	1 - 2 - 3	development, production	.env file, Heroku app
POSTGRES_PASSWORD	Password of the admin user of the database.	1 - 2 - 3	development, production	.env file, Heroku app
POSTGRES_DB	Name of the database.	1 - 2 - 3	development, production	.env file, Heroku app
POSTGRES_HOST	Hosting address of the database.	1 - 2 - 3	development, production	.env file, Heroku app
DATABASE_URL	Full connection PostgreSQL connection string of the database.	1 - 2 - 3	development, production	.env file, Heroku app
SMTP_USERNAME	Username of the SMTP mail server.	1 - 2 - 3	production	.env file, Heroku app
SMTP_PASSWORD	Password of the SMTP mail server.	1 - 2 - 3	production	.env file, Heroku app
SMTP_DOMAIN_NAME	Domain of the SMTP mail server.	1 - 2 - 3	production	.env file, Heroku app
SMTP_DOMAIN_ADDRESS	Full address of the SMTP mail server.	1 - 2 - 3	production	.env file, Heroku app
EMAIL_BUG_REPORT	Email address to receive bug reports.	1 - 2 - 3	development, production	.env file, Heroku app
EMAIL_ADMIN	Email address to receive general questions.	1 - 2 - 3	development, production	.env file, Heroku app
RAILS_LOG_TO_STD	When set to true, forces the application to write its logs to the standard output.	1 - 2 - 3	production	.env file, Heroku app

Setting Variables

To set an environment variable in a local .env file, create it inside the main directory of RS_Server. Then, populate it in a key=value fashion. To set an environment variable in a Heroku app, simply follow this guide. In Heroku terminology, environment variables are called config vars.

To provide an example, the following is the content of a valid .env file.

SECRET_PROD_KEY=your_secret_prod_key_value
DATABASE_URL=your_postgresql_database_connection_string
SMTP_USERNAME=your_smtp_username
SMTP_PASSWORD=your_smtp_password
SMTP_DOMAIN_NAME=your_smtp_domain_name
SMTP_DOMAIN_ADDRESS=your_smtp_domain_address
EMAIL_BUG_REPORT=your_bug_report_mail
EMAIL_ADMIN=your_contact_mail

Sending Mails

RS_Server supports any SMTP-based mail server to send emails for tasks such as confirming user registration, reporting bugs, or recovering forgotten passwords.

Understanding the values used to populate the SMTP_ environment variables can sometimes lead to ambiguity. Let's consider the case of the proposed add-on, Twilio Sendgrid, both when deploying RS_Server manually and on Heroku. In the first case, after creating an account, you need to verify a single sender address or a whole domain using the provided DNS records. To integrate the service into an instance of RS_Server deployed anywhere outside Heroku, you must use a supported SMTP configuration. Thus, the values of the environment variables must be in this form:

• SMTP_USERNAME: apikey
• SMTP_PASSWORD: <your_api_key_value>
• SMTP_DOMAIN_NAME: <your_domain_address>
• SMTP_DOMAIN_ADDRESS: smtp.sendgrid.net

However, while using the addon provided by Heroku, the values provided for the environment variables need to be slightly different:

• SMTP_USERNAME: <your_sendgrid_account_username>
• SMTP_PASSWORD: <your_sengrid_password_account>
• SMTP_DOMAIN_NAME: <your_domain_address>
• SMTP_DOMAIN_ADDRESS: smtp.sendgrid.net

Connecting To The Database

A full connection string to a PostgreSQL database provided through the DATABASE_URL variable takes precedence over each POSTGRES_ variable. It is thus important to provide the former environment variable or the set of the latter ones. This holds for both the development and production environments. Indeed, the final connection string is built as such:

<%= ENV['DATABASE_URL'] || "postgresql://#{ENV['POSTGRES_USER'] || 'postgres'}:#{ENV['POSTGRES_PASSWORD']}@#{ENV['POSTGRES_HOST'] || 'localhost'}/#{ENV['POSTGRES_DB'] || 'rs_server'}" %>

Logging To The Standard Output

An instance of RS_Server deployed in development writes its logs to the standard output as the default behavior. In a production environment, on the other hand, the logs are written in the logs/production.log file. Thus, forcing Rails to write logs in the standard output using the RAILS_LOG_TO_STD variable can be useful for quick debugging purposes when testing the production environment.