Skip to content

Important

We have planned several installation methods for this project, it is nevertheless recommended using a Linux environment.

Important

It is recommended to have at least 20 GB of free space on your machine (The database takes up a little more than 11 GB).

Production environment

In a production environment, all you need is a docker.

We advise you to use this environment in the following cases:

  • To deploy the application on a server
  • To test the application locally (in your computer)
  • To contribute to the project
  • To test services independently of the full application

Development environment

In a development environment, there will be several dependencies to install.

We advise you to use this environment in the following cases:

  • To contribute to the project with hot reloading
  • If you want to access the database via an interface
  • If you are on Windows and you don't want to use our solution: https://github.com/RomainCtl/vagrant_docker (more information in the guide)

Requirements

In order to be able to deploy, test or make changes to the application, you must have the necessary tools to run the application.

  1. make
  2. git & git lfs (Large File Storage)
  3. docker & docker-compose

and that's all!

make is normally installed by default.

Install git and git-lfs: 

apt install git git-lfs
git lfs install

You can install docker simply with: 

apt install docker.io docker-compose

Download git from here and follow the instruction.

Download git lfs from here and: 

git lfs install

If you work on windows, I advise you to follow the instructions in this repository: https://github.com/RomainCtl/vagrant_docker

So, each time you will use docker, you may start the vm (make vm-up).

Note

An Oracle VM Virtualbox will start and you will see it, you do not need to log on to it. The author of this repository chose to leave the VM window open to do not forget to switch it off before turning off the computer.

Tip

To use docker, do not forget to define the environment variables as the following: ./setenv-docker.bat.

For make, you will have to install the "Developer Tools" that are provided as optional packages in OS X installation disks.

git is normally installed by default, try: 

git --version
on your terminal, if it is not already installed, it will ask you to do so.

Install git-lfs: 

brew install git-lfs
git lfs install

Docker Compose is installed as part of Docker for Mac. So you only have to install Docker for MAC.

Warning

This guide may not work on your environment, if this is the case, please refer to the official sites of the outbuildings.

This guide is only intended to help you with the installation, but not with the configuration of the dependencies.

In order to be able to make changes to the application or to access the database via an interface, you must have the necessary tools to run the application.

  1. make
  2. git & git lfs (Large File Storage)
  3. python>=3.8, pip and pipenv
  4. npm
  5. postgresql>=10
  6. java>=11

make is normally installed by default.

Install git and git-lfs: 

apt install git git-lfs
git lfs install

Python 3.8, pip & pipenv 

apt install python3.8 python3-pip
python3 -m pip install pipenv

Tip

If you have more than one version of Python installed on your machine, the python3 command may execute a different version,

See : https://jcutrer.com/linux/upgrade-python37-ubuntu1810 (taking into account the desired version).

Npm 

apt install nodejs

PostgreSQL 

apt install postgresql postgresql-client

Java 

apt install openjdk-11-jre

Important

We advise you to install:

  1. Choco, software management for windows
  2. Cmder, it is a command-line tool, it allows to replace advantageously cmd provided by default by Windows.

Make 

choco install -y make

Download git from here and follow the instruction.

Download git lfs from here and: 

git lfs install

Python3.8 https://www.python.org/downloads/windows/, do not forget to tick the box "add to path".

Npm, included with NodeJS https://nodejs.org/en/download/

PostgreSQL https://www.postgresql.org/download/

Java https://www.oracle.com/java/technologies/javase-jdk11-downloads.html

For make, you will have to install the "Developer Tools" that are provided as optional packages in OS X installation disks.

git is normally installed by default, try: 

git --version
on your terminal, if it is not already installed, it will ask you to do so.

Install git-lfs: 

brew install git-lfs
git lfs install

Python 3.8 https://www.python.org/downloads/mac-osx/

Npm, included with NodeJS https://nodejs.org/en/download/

PostgreSQL https://www.postgresql.org/download/

Java https://www.oracle.com/java/technologies/javase-jdk11-downloads.html

Clone project

We use a micro-service architecture (more information in this section). We have a "master project" which has all services as sub-modules.

Clone the "master project" and follow these commands: 

git clone https://github.com/RomainCtl/RecoFinement.git
Imports git submodule (services) 
make init
Import our data (may take some time depending on your internet connection) 
cd ./datas
git lfs pull
cd ..

Environment variables

In order to run correctly, the project needs to recover its configuration.

Tip

If you need to generate some random string, you can use this command: 

python3 -c "import random; print(''.join(random.choice('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!%*+-:;@_') for _ in range(30)))"

API

To do so, just copy the .env.default file: 

cd services/api
cp .env.default .env
Then replace the values, and in particular the variables for the connection to the database.

Generate some random string for DB_USER_LOGIN, DB_USER_PASSWORD, ENGINE_APIKEY and SECRET_KEY

You need to create recofinement database, when you created this one, you must have entered a user who owns this database. DB_USER_LOGIN and DB_USER_PASSWORD variables are its identifiers.

Generate some random string for SECRET_KEY and ENGINE_APIKEY.

Warning

This api uses some external services, and you need to configure them. You will find a guide on their respective pages:

  1. Mailjet
  2. Spotify
  3. TMDB
  4. Google Books

Anyway, you can use Recofinement without these features, users will simply not be able to receive email nor to link their account to the services mentioned.

Engine

First, just copy the .env.default file: 

cd services/reco_engine
cp .env.default .env
Then replace the values.

You only need to set DB_USER_LOGIN, DB_USER_PASSWORD, FLASK_SECRET and API_TOKEN variables.

FLASK_SECRET must be a random string (can also use the command above).

DB_USER_LOGIN and DB_USER_PASSWORD are the same as those used for the api.

API_TOKEN corresponds to the variable ENGINE_APIKEY in the api.

Import data

Info

The database schema is created with the api (with an ORM)

Danger

Depending on the performance of the machine you are using, this operation may take some time (several hours).

  1. Build docker image for the database and the api 
    make db-build api-build
  2. Start database and api container 
    make db api
  3. Import data 
    make import-data
If you want to see logs
make logs
  1. Make sure that the database service is running (with a recofinement database created).
  2. Let's create the database schema: 
    cd services/api
make init
make db-update
cd  ../..
  3. Edit the importation script: 
    cd datas
# Replace "<pwd>" by the current absolute path (important!)
sed -i "s#FROM '#FROM '<pwd>#g" script.sql
  4. Execute this script on your database

Usage

Usually Docker uses the default 172.17.0.1/16 subnet for container networking.

If you use Windows

You may write the following line into .env file (This is the ip used to access the docker hub). 

DOCKER_IP=192.168.56.10

  1. Build docker image from sources (all services) 
    make build
  2. Start the container (all services) 
    make start
  3. Display logs from the running container (all services) 
    make logs
  4. Stop the container (all services) 
    make stop
  5. Destroy the container (all services) 
    make rm

You can also do each action for one service using: 

## (Re)start 'api' service only (also available: 'api-[build|logs|sh|stop|rm])
make api

## (Re)start 'engine' service only (also available: 'engine-[build|logs|sh|stop|rm])
make engine

## (Re)start 'cron' service only (also available: 'cron-[build|logs|sh|stop|rm])
make cron

## (Re)start 'db' service only (also available: 'db-[build|logs|sh|stop|rm])
make db

## (Re)start 'front' service only (also available: 'front-[build|logs|sh|stop|rm])
make front

## (Re)start 'nginx' service only (also available: 'nginx-[build|logs|sh|stop|rm])
make nginx

UI Service:

  1. Install dependencies 
    make init
  2. Serve locally the development build (with hot-reloads) 
    make serve
# or
ng serve

API Service:

  1. Install dependencies 
    make init
  2. Update database to the last migration (or initialize it if it does not exist) 
    make db-update
  3. Serve locally the development build 
    make serve

Engine Service:

  1. Install dependencies 
    make init
  2. Serve locally the development build 
    make serve

Tip

If you want to know more about the available orders and how you can contribute to the project, we invite you to look at the 'README.md' files of each repository.

You can access it by clicking on the github button at the top right of this site.

Add the admin role to a user

Important

It is preferable to have imported the data beforehand (see here) and to have created a user (register).

  1. Connect to your db container 
    make db-sh
  2. Connect to the db 
    psql -d <db_name> -U <user_name>
  3. Find your user_id 
    SELECT user_id from public.user WHERE email = '<your email>';
  4. Add the admin role 
    INSERT INTO public.user_role VALUES (<user_id>, 2);
  1. Connect to the db 
    psql -d <db_name> -U <user_name>
  2. Find your user_id 
    SELECT user_id from public.user WHERE email = '<your email>';
  3. Add the admin role 
    INSERT INTO public.user_role VALUES (<user_id>, 2);