# Tutorial 2: How to use MOSAIC

This tutorial shows you, how to setup and run the *Modular Search Application based on Index Fraction* (MOSAIC). More detailed information can be found in the [README](https://opencode.it4i.eu/openwebsearcheu-public/mosaic/-/blob/main/README.md) of the MOSAIC project


## 1) Prerequisites

MOSAIC has been developed for and tested on Linux (Ubuntu 22 and 24). However it should also work on MacOS and Windows. 

In order to download and try out MOSAIC, the following software applications are needed:
- Git (for downloading/cloning MOSAIC; alternatively MOSAIC can also be downloaded as ZIP file)
- Java JDK v21 (for building and starting MOSAIC)
- Docker (for building and starting MOSAIC)

## 2) Download, build, and start the MOSAIC service

Download the MOSAIC souce code from [GitLab](https://opencode.it4i.eu/openwebsearcheu-public/mosaic.git) as Zip file or with git.

```bash
git clone https://opencode.it4i.eu/openwebsearcheu-public/mosaic.git
```

Navigate to the scripts directory of MOSAIC with your console and use the build and start script. 

```bash
cd <path-to-mosaic>/scripts/
./build.sh 
./start.sh
```

In order to stop the service, press Ctrl-c. 

```{hint}
For more details on starting the MOSAIC search service, please take a look at [available options](https://opencode.it4i.eu/openwebsearcheu-public/mosaic/-/blob/main/README.md#cli-options). For example, you can start the service using a different port. 
```


## 3) Test the REST API and the web interface

Open a web browser to test the endpoints of the REST API.

```bash
http://localhost:8008/index-info
http://localhost:8008/search?q=<search-term>
```

```{hint}
For more details on testing and using the REST API, please take a look at the [available endpoints](https://opencode.it4i.eu/openwebsearcheu-public/mosaic/-/blob/main/README.md#service-access), the [supported query parameters](https://opencode.it4i.eu/openwebsearcheu-public/mosaic/-/blob/main/README.md#query-parameters) and the [response format](https://opencode.it4i.eu/openwebsearcheu-public/mosaic/-/blob/main/README.md#response-json).
```

The MOSAIC source code includes a simple web interface for the REST API in the front-end directory.

Open the `front-end/index.html` file in your web browser and try out the search. 


## 4) Run MOSAIC in Docker
As an alternative to cloning or downloading the repository, you can run MOSAIC using the Docker images available from the Gitlab Container registry.

Use the following Docker command to run MOSAIC with the indexes that come with the MOSAIC source code:
```bash
docker run \
    --rm \
    -p 8008:8008 \
    opencode.it4i.eu:5050/openwebsearcheu-public/mosaic
```

If you want to use other indexes, you can start the MOSAIC search service with the options `--lucene-dir-path` and `--parquet-dir-path`:
```bash
docker run \
    --rm \
    -v "<path-to-index-files>":/data:Z \
    -p 8008:8008 \
    opencode.it4i.eu:5050/openwebsearcheu-public/mosaic/search-service \
    --lucene-dir-path /data/lucene/ \
    --parquet-dir-path /data/metadata/
```


## 5) Include your own index slice to MOSAIC

You can add your own index slice (CIFF and Parquet file) to MOSAIC:
- Take an index slice from the `.owi` folder that has been dowloaded with `owilix`.
- Download an example index from the [demo indices page](https://cloud.tugraz.at/index.php/s/xHnJNCozT9joedt). 

Then create a folder in the MOSAIC resource directory (`resource/[folder-name]`) and copy CIFF and Parquet file to this folder.
- path-to-mosaic
  - resource 
    - simplewiki
      - index.ciff
      - metadata.parquet
    - harry-potter
      - index.ciff.gz
      - metadata.parquet
    - ...


Finally, stop, build, and start the service (see above).

```bash
cd <path-to-mosaic>/scripts/
./build.sh 
./start.sh
```