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