Readersourcing 2.0: An independent, third-party, no-profit, academic project aimed at quality rating of scholarly literature and scholars.
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.
- 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
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.
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.
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.
- Ruby == 2.7.8;
- JDK (Java Development Kit) == 11.0.19;
- PostgreSQL >= 11.2.
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.1
IP address with port 3000
and development
environment.
Every HTPP request, therefore, must be sent to the http://127.0.0.1:3000
address.
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
orrails server -b <your_ip_address> -p <your_port> -e production
.
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.
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.
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
.
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
.
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).
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.
- Heroku account;
- Heroku application provisioned with:
- PostgreSQL addon;
- a mail-related addon such as Twilio SendGrid;
- Heroku CLI;
- Docker Desktop CE (Community Edition).
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.
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.
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 |
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
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
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'}" %>
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.