installation.md

# Installation

## Introduction

Here are the steps to follow to install the software locally on your machine.
The examples are realized on a linux system.

ANIS is composed of a monorepo projects that contains a `server`, a `client`,
some `services` and some `tasks`. We will see how to install the stack.

## Git Repository

The ANIS source code is available on a public gitlab repository.
Here we will retrieve the ANIS project by cloning the official git project.

```bash
$ git clone git@gitlab.lam.fr:anis/anis.git
$ cd anis
```

## Docker & docker-compose

ANIS is designed to work through docker containers and each part of ANIS (`server`, `client`, `services` and `tasks`) will run in four respective containers.

In the development mode, ANIS provides a `docker-compose` file that allows the management of containers (start, stop, restart, logs, ect...).
You can find the `docker-compose.yml` file at the root of the project. It aims to list all the containers necessary for the operation of ANIS.

To operate ANIS needs, in addition to the four containers mentioned above, several other containers:

 - `keycloak`: Single sign-on with identity and access management. Used in ANIS to manage user accounts and dataset rights.
 - `postgres`: Database management system used to install the configuration database and the test business database.
 - `rabbitmq`: Message-broker software used to launch asynchronous tasks.
 - `maildev`: Software used to send or receive emails in dev mode.

## Makefile

ANIS contains a `Makefile` that helps the developer to install and start the application.
The latter `Makefile` defines CLI shortcuts for docker commands used to manage the different latter containers.
Just for information, to list all available operations just type `make` in your terminal.

![anis_make](img/anis_make.png)

**Warning**: If you encounter problems with file permissions, check in the Makefile the `UID` and `GID` variables. 
The `UID` and `GID` must match your user and group. By default the  `UID` and `GID` is set to `1000:1000`.

## Dependencies

### Install client dependencies

The client part is written with Angular/TypeScript and requires dependencies to work.
To install type this make command:

```bash
$ make install_client
```

The client dependencies packages will be downloaded and placed in a folder named `client/node_modules`. This may take a few minutes.
Just for information, you can find the list of dependencies in the `client/package.json` file.

### Install server dependencies

The server part is written with PHP and requires dependencies to work.
To install type this make command:

```bash
$ make install_server
```

The server dependencies packages will be downloaded and placed in a folder named `server/vendor`. This may take a few minutes.
Just for information, you can find the list of dependencies in the `server/composer.json` file.

### Install services and tasks dependencies

The services and the tasks part are written in pure python.
The dependencies for the latter are installed upon first build normally.

Nevertheless, you can still install specified dependencies using the commands:
```bash
$ make install_services
```

```bash
$ make install_tasks
```

## Data

To works, ANIS must be associated with a data directory. This directory will serve files associated with scientific projects and datasets.

In the dev version we provide a data directory with examples files. To install them type the following command:

```bash
$ cd ..
$ wget https://anis.lam.fr/files/anis-data.tar.gz
$ tar xvf anis-data.tar.gz
$ rm anis-data.tar.gz
```

At the root of the project you can see a symbolic link to the directory you just downloaded: `data`.

## Start application

It is now time to start the ANIS stack. To do this use the following make command:

```bash
$ cd anis
$ make start
```

This command will use the `docker-compose.yml` file to create and launch the different containers needed for ANIS.
This may also take a few minutes. You can see the status of ANIS containers by typing the following command:

```bash
$ make status
```

You can also follow the containers logs by typing: 

```bash
$ make logs
```

**Warning**: Just wait few seconds that software completely started to continue this procedure guide.

## Databases

To works ANIS need at least two databases: 

 - One database to store the configuration
 - At least one database containing datasets

In the dev version we provide two ready-made databases. To install them type the following command:

```bash
$ make create-db
```

## ANIS is ready to use!

### Server

* The server API is available at the following address: `http://localhost:8080`

![anis_server_root](img/anis_server_root.png)

Here are a few examples to query the server:

* To list all instances configured and available:
    * `http://localhost:8080/instance`
* To list all datasets available and configured within the ***default*** instance:
    * `http://localhost:8080/instance/default/dataset`
* To print all data for the ***observations*** dataset with column 1, 2 and 3 configured within the ***default*** instance:
    * `http://localhost:8080/search/default/observations?a=1;2;3`
* To count number of data available for the ***observations*** dataset configured within the ***default*** instance:
    * `http://localhost:8080/search/default/observations?a=count`
* To print only 3 observations data (search by id) from the ***observations*** dataset configured within the ***default*** instance:
    * `http://localhost:8080/search/default/observations?a=1;2;3&c=1::in::418|419|420`

### Client

* The web-ui client is available at the following address: `http://localhost:4200` and you can start 
using the application with the test data.

### Services

* The services are available at the following address: `http://localhost:5000`