diff --git a/README.md b/README.md
index 9d94816..3d8614e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,32 @@
 # RandomRedditMemesAPI
 
-an API that returns random Reddit Submissions written in Java
\ No newline at end of file
+an API that returns random Reddit Submissions written in Java
+
+## build and run
+
+### build project
+first make sure you're using Gradle 6.8 and openjdk-jdk8
+
+to build the project just run:
+```
+gradle build
+```
+
+### run
+to execute the .jar archive you built before run:
+```
+java -jar ./build/libs/RandomRedditMemesAPI.jar
+```
+
+### run inside docker
+to execute the .jar file inside docker use docker-compose:
+```
+docker-compose -p RandomRedditMemesAPI up -docker
+```
+
+### build docker image
+if you want to build a full docker image run:
+```
+docker build .
+```
+alternatively you can use `./docker/docker-compose.yml`