@@ -23,219 +21,112 @@ This software is free (as "Libre" in French) software, developed by the CNRS Com
GarganText Project: this repo builds the backend for the frontend server built by [backend](https://gitlab.iscpif.fr/gargantext/haskell-gargantext).
## Installation <a name="install"></a>
## Installation and development <a name="install"></a>
Disclaimer: since this project is still in development, this document remains in progress. Please report and improve this documentation if you encounter any issues.
As said, Gargantext requires [Nix](https://github.com/NixOS/nix) to provide system dependencies (for example, C libraries), but its use is limited to that. In order to install[Nix](https://nixos.org/download.html):
#### Clone the projects
Clone both the backend (`haskell-gargantext`), and the frontend (`purescript-gargantext`) at the root of the backend.
```shell
sh <(curl -L https://nixos.org/nix/install) --daemon
**Important:** Before building the project with either `stack` or `cabal` you need to be in the correct Nix shell, which will fetch all the required system dependencies. To do so, just type **inside your haskell-gargantext folder**:
#### Enter a Nix shell
Enter a Nix shell. This will take a long time the first time you run it:
```shell
nix-shell
```
This will take a bit of time as it has to download/build the dependencies, but this will be needed only the first time.
### Build: choose cabal (new) or stack (old)
#### With Cabal (recommanded)
##### Turning off optimization flags
Create a `cabal.project.local` file (don't commit it to git!):
You can exit a Nix shell at any point with `exit`.
package gargantext-invitations
ghc-options: -O0
In what follows, many commands need to be executed from within the Nix shell. To make that clear, those will be prefixed with `n$`, *but you must not actually type `n$` before the commands*.
package gargantext-phylo
ghc-options: -O0
package gargantext-server
ghc-options: -O0
package gargantext-upgrade
ghc-options: -O0
package gargantext-graph
ghc-options: -O0
package hmatrix
ghc-options: -O0
package sparse-linear
ghc-options: -O0
```
##### Building
First, into `nix-shell`:
If for some reason you do not want to enter a Nix shell, you can still run a command from outside:
```shell
cabal update
cabal install
nix-shell --run"my command"
```
is equivalent to running `my command` from within a Nix shell.
Alternatively, if you want to run the command "from the outside", in your current shell:
#### Disable optimization flags
```
nix-shell --run "cabal update"
nix-shell --run "cabal install"
Make a file `cabal.project.local` that will tell Cabal to turn off optimizations:
*Note: This project can be built with either stack or cabal. We keep the `cabal.project` up-to-date, which allows us to build with cabal by default but we support stack thanks to thanks to `cabal2stack`, which allows us to generate a valid `stack.yaml` from a `cabal.project`. Due to the fact gargantext requires a particular set of system dependencies (C++ libraries, toolchains, etc) we use nix to setup an environment with all the required system dependencies, in a sandboxed and isolated fashion.*
```shell
curl -sSL https://get.haskellstack.org/ | sh
```
*This documentation shows how to build with cabal. For information related to stack, see `docs/using_stack.md`.*
Verify the installation is complete with
**From within the Nix shell**, run:
```shell
stack --version
Version 2.9.1
n$ cabal update
n$ cabal install
```
NOTE: Default build (with optimizations) requires large amounts of RAM (16GB at least). To avoid heavy compilation times and swapping out your machine, it is recommended to `stack build` with the `--fast` flag, i.e.:
#### Build the backend and frontend
```shell
stack build --fast
./bin/install
cd purescript-gargantext/
./bin/install
cd ..
```
### Initializing and running
#### Keeping the stack.yaml updated with the cabal.project
(Section for Developers using stack only)
Once you have a valid version of `stack`, building requires generating a valid `stack.yaml`.
This can be obtained by installing `cabal2stack`:
#### Start containers for database and NLP software bricks
The good news is that you don't have to do all of this manually; during development, after modifying the
`cabal.project`, it's enough to do:
```shell
./bin/update-project-dependencies
```
## Initialization <a name="init"></a>
#### 1. Docker-compose will configure your database and some NLP bricks (such as CoreNLP):
First install docker-compose on your system and then:
``` sh
docker compose up
```
Initialization schema should be loaded automatically (from `devops/postgres/schema.sql`).
##### (Optional) If using stack, then install:
``` sh
stack install
```
#### 2. Copy the configuration file:
``` sh
cp gargantext.ini_toModify gargantext.ini
```
> Do not worry, `.gitignore` avoids adding this file to the repository by mistake, then you can change the passwords in gargantext.ini safely.
#### 3. A user have to be created first as instance:
In your nix-shell
``` sh
gargantext-cli init --ini-path "gargantext.ini"
```
Now, `user1` is created with password `1resu`
#### 4. Clone FRONTEND repository:
> `.gitignore` excludes this file, so you don't need to worry about committing it by mistake, and you can change the passwords in `gargantext.ini` safely.
From the Backend root folder (haskell-gargantext):
> **Note:** here, the method with Cabal is used as default
The master user's name is automatically set to `gargantua`, but you will be prompted for their password and email address.
#### Running
From the Backend root folder (haskell-gargantext):
``` shell
./start
# The start script runs following commands:
# - `./bin/install` to update and build the project
# - `docker compose up` to run the Docker for postgresql from devops/docker folder
# - `cabal run gargantext-server -- --ini gargantext.ini --run Prod` to run other services through `nix-shell`
From inside a Nix shell:
```shell
n$ cabal run gargantext-server ----ini gargantext.ini --run Prod
```
For frontend development and compilation, see the [Frontend Readme.md](https://gitlab.iscpif.fr/gargantext/purescript-gargantext#dev)
If you are working on the backend, you might want to use the `./start` script: it rebuilds the backend, starts the docker containers, and launches the Gargantext server at once.
### Running tests
...
...
@@ -391,7 +282,6 @@ Maybe you need to change the port to 5433 for database connection in your gargan
## `haskell-language-server`
If you want to use `haskell-language-server` for GHC 9.4.7, install it
Those are the instructions for developers who wish to build Gargantext using stack instead of cabal.
## Prerequisites
You need [Stack](https://docs.haskellstack.org/en/stable/)(obviously). You can install it with:
```shell
curl -sSL https://get.haskellstack.org/ | sh
```
Check that the installation is complete with:
```shell
stack --version
Version 2.9.1
```
## Building and setting up
To build with stack, follow the instructions in `README.md`, with the following changes:
- Replace the `cabal update` and `cabal install` commands with (still from within a Nix shell!):
```shell
stack build --fast
```
*Note: The default build (with optimizations) requires large amounts of RAM (16GB at least). The (recommended) `--fast` flag is here to avoid heavy compilation times and swapping out your machine; just omit it if you want to build with optimizations.*
- After you have run the `docker compose up` command, install with
```shell
stack install
```
## Keeping the stack.yaml updated with the cabal.project
Once you have a valid version of stack, building requires generating a valid `stack.yaml`. This can be obtained by installing `cabal2stack`:
