diff --git a/.gitignore b/.gitignore
index 42196ce..ea1f815 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-README.md
 target/
 !.mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4043ae7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# OpenAIRE Search API v2
+
+Welcome to the OpenAIRE Search API v2 code repository! 
+
+This repository houses the latest implementation of our OpenAIRE Search API, 
+designed to facilitate seamless access to metadata records of research products (i.e., publications, data, software, other research products), and projects
+within the OpenAIRE Graph. 
+
+For more information, please take a look at our [documentation page](https://graph.openaire.eu/docs/apis/search-api/).
+
+
+
+# Getting Started
+
+### Reference for developers
+- This project is built with Java 21; tested using OpenJDK 21.0.2
+
+- Before starting the application, please load env variables from `.env` file; using `source .env` will do the job for most systems
+
+### Docker support
+
+Create a docker image using:
+
+```shell
+# building the jar file
+mvn install 
+
+# building the actual docker image
+docker build -t openaire-search-api-v2:latest . 
+```
+
+Start a docker container as follows: 
+
+```shell
+# load required env variables
+source .env
+
+# start docker container
+docker run -it -p 8080:8080 openaire-search-api-v2:latest .
+```
+
+or using docker compose:
+```shell
+# adjust env variables in docker-compose.yml
+
+# start container using docker compose 
+docker compose up -d
+```
+
+
+