diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b8f125
--- /dev/null
+++ b/README.md
@@ -0,0 +1,228 @@
+# Lithium
+
+Micro-service for file storage and processing written in Go.
+
+## Features
+
+- Image processing pipelines for various transformations
+- Web API for storing & retrieving files
+
+## Requirements
+
+- [Go 1.17+](https://go.dev/)
+- [*Docker*](https://docs.docker.com/) (optional)
+
+## Setup
+
+#### 1. Clone repository
+
+```shell
+git clone git@gogs.informatik.hs-fulda.de:FabianVowie/Lithium.git
+```
+
+#### 2. Pull dependencies
+
+```shell
+go get
+```
+
+#### 3. Build & start application
+
+```shell
+go run .
+```
+
+**Run using [Docker](https://docs.docker.com/) container**
+
+```shell
+docker run --rm -p 8000:8000 -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go run .
+```
+
+## Testing
+
+```shell
+go test ./...
+```
+
+### Run tests in verbose logging mode
+
+```shell
+go test ./... -v
+```
+
+### Run tests in [Docker](https://docs.docker.com/) container
+
+```shell
+docker run --rm -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go test ./...
+```
+
+## API
+
+### `GET` `/`
+
+Show application information. 
+
+**Example response**:
+
+```json
+{
+  "Name": "Lithium",
+  "Version": "0.1.0"
+}
+```
+
+### `GET` `/{pipeline}`
+
+Show pipeline information.
+
+**Example response**:
+
+```json
+{
+  "name": "example pipeline",
+  "slug": "example",
+  "type": 0,
+  "remove_metadata": false,
+  "steps": [
+    {
+      "name": "resize image",
+      "type": 0,
+      "options": {
+        "width": 1280,
+        "height": 720,
+        "upscale": false
+      }
+    }
+  ],
+  "output": {
+    "format": 0,
+    "quality": 90
+  }
+}
+```
+
+## Configuration
+
+Config options can be adjusted via the [`settings.json`](settings.json) file in the root directory.
+
+```json
+{
+  "endpoint": "0.0.0.0:8000",
+  "token": "changeme",
+  "storage_provider": {
+    "type": 0,
+    "base_path": "assets"
+  }
+}
+```
+
+## Pipelines
+
+The project uses a pipeline system defined by [JSON](https://en.wikipedia.org/wiki/JSON) files located in the [config](config) folder.
+Take a look at the [example pipeline configuration file](config/example.json).
+
+Available pipeline `type`s:  `0` (Image), `1` (Video)
+
+```json
+{
+  "name": "example pipeline",
+  "slug": "example",
+  "type": 0,
+  "removeMetadata": false,
+  "steps": [],
+  "output": {}
+}
+```
+
+### Images pipeline
+
+The image pipeline offers the following additional output options.
+
+Available `format` types: `0` (jpeg)    
+The `quality` field can contain any integer between 1 and 100.
+
+```json
+{
+  "output": {
+    "format": 0,
+    "quality": 90
+  }
+}
+```
+
+### Available pipeline steps
+
+Each pipeline step consists of an optional `name`, a predefined `type` and configurable `options`.
+See the available options below for more information.
+
+```json
+{
+  "name": "step name",
+  "type": 0,
+  "options": {}
+}
+```
+
+#### Resizing images
+
+Resize an image by a given `width` and `height`.
+
+**Step definition**:
+
+```json
+{
+  "type": 0,
+  "options": {
+    "width": 1280,
+    "height": 720
+  }
+}
+```
+
+#### Rotating images
+
+Rotate an image with a given `angle` in degrees.
+
+**Step definition**:
+
+```json
+{
+  "type": 1,
+  "options": {
+    "angle": 90.0
+  }
+}
+```
+
+#### Flipping images
+
+Flip an image with a given direction.
+Allowed values for the `direction` option are `"h"` (horizontal), `"v"` (vertical)
+
+**Step definition**:
+
+```json
+{
+  "type": 2,
+  "options": {
+    "direction": "h"
+  }
+}
+```
+
+#### Grayscale
+
+Convert the colorspace of an image into grayscale.
+
+**Step definition**:
+
+```json
+{
+  "type": 3
+}
+```
+
+## Authors
+
+- [Fabian Vowie](https://gogs.informatik.hs-fulda.de/FabianVowie)
+- [Roman Zipp](https://gogs.informatik.hs-fulda.de/roman.zipp)
diff --git a/lithium.md b/lithium.md
deleted file mode 100644
index 6d0ed5c..0000000
--- a/lithium.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Lithium
-
-Micro-service for file storage and processing.
-
-## Features
-
-- File storing with various providers
-  - S3 (or S3 compatible like MinIO)
-  - Locally (for development purposes)
-- File processing "pipelines" for various formats
-  - Compression, Resizing for images
-  - Encoding for videos
-  - Remove metadata (e.g. EXIF)
-- File-based configuration for pipelines
-  - JSON/YAML/TOML?
-- Web api to store and retrieve files