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 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 as Zip file or with git.

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.

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. 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.

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, the supported query parameters and the response format.

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:

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:

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.

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).

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