diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a7bbe5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# 12 Factor Demo Deployment guide
+
+## Java
+
+Download the jar from the [releases](/releases) page.
+
+Create a configuration file (`config/application.properties`) with the following content
+
+```
+SERVER_PORT=8080
+CUSTOM_MESSAGE="Hello World From Configs"
+
+# use the endpoint if you are using minio
+AWS_ENDPOINT=http://localhost:9000
+# use the region if you are using AWS S3
+#AWS_REGION=us-east-1
+
+AWS_ACCESS_KEY=myuser
+AWS_SECRET_KEY=mypassword
+```
+
+Run the minio docker compose file
+
+```bash
+docker-compose -f src/main/docker/minio.yml up
+```
+
+Run the application
+
+```bash
+java -jar 12-factor-app.jar
+```
+
+## Docker Compose
+
+Run the entire app using docker compose
+
+```
+docker-compose -f src/main/docker/12-factor.yml up
+```
+
+## Kubernetes
+
+Run the kustomization file
+
+```
+kubectl apply -k src/main/kubernetes/kustomization.yml
+```
diff --git a/src/main/docker/12-factor.yml b/src/main/docker/12-factor.yml
new file mode 100644
index 0000000..fcbd3d8
--- /dev/null
+++ b/src/main/docker/12-factor.yml
@@ -0,0 +1,23 @@
+version: '3'
+services:
+  12-factor-demo:
+    image: intesys/twelve-factor-app:latest
+    environment:
+      - SERVER_PORT=8080
+      - CUSTOM_MESSAGE=Hello World From Docker
+      - AWS_ENDPOINT=http://minio:9000
+      - AWS_ACCESS_KEY=myuser
+      - AWS_SECRET_KEY=mypassword
+    ports:
+      - 8085:8080
+  minio:
+    image: minio/minio:latest
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      - MINIO_ROOT_USER=myuser
+      - MINIO_ROOT_PASSWORD=mypassword
+    volumes:
+      - ./data:/data
+    command: server /data --console-address ":9001"
diff --git a/src/main/kubernetes/kustomization.yml b/src/main/kubernetes/kustomization.yml
new file mode 100644
index 0000000..1e6bfda
--- /dev/null
+++ b/src/main/kubernetes/kustomization.yml
@@ -0,0 +1,11 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: academy
+
+resources:
+  - 12-factor-demo-deployment.yaml
+  - minio-deployment.yaml
+
+commonLabels:
+  app: 12-factor-demo
+
diff --git a/src/main/kubernetes/minio-deployment.yaml b/src/main/kubernetes/minio-deployment.yaml
new file mode 100644
index 0000000..0462ea1
--- /dev/null
+++ b/src/main/kubernetes/minio-deployment.yaml
@@ -0,0 +1,46 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: minio
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: minio
+  template:
+    metadata:
+      labels:
+        app: minio
+    spec:
+      containers:
+        - name: minio
+          image: minio/minio:latest
+          ports:
+            - containerPort: 9000
+            - containerPort: 9001
+          env:
+            - name: MINIO_ROOT_USER
+              value: "myuser"
+            - name: MINIO_ROOT_PASSWORD
+              value: "mypassword"
+          volumeMounts:
+            - name: data-volume
+              mountPath: /data
+      volumes:
+        - name: data-volume
+          emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: minio-service
+spec:
+  selector:
+    app: minio
+  ports:
+    - protocol: TCP
+      port: 9000
+      targetPort: 9000
+    - protocol: TCP
+      port: 9001
+      targetPort: 9001
diff --git a/src/main/kubernetes/twelve-factory.yml b/src/main/kubernetes/twelve-factory.yml
new file mode 100644
index 0000000..8e44926
--- /dev/null
+++ b/src/main/kubernetes/twelve-factory.yml
@@ -0,0 +1,42 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: 12-factor-demo
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: 12-factor-demo
+  template:
+    metadata:
+      labels:
+        app: 12-factor-demo
+    spec:
+      containers:
+        - name: 12-factor-demo
+          image: intesys/twelve-factor-app:latest
+          ports:
+            - containerPort: 8080
+          env:
+            - name: SERVER_PORT
+              value: "8080"
+            - name: CUSTOM_MESSAGE
+              value: "Hello World From Docker"
+            - name: AWS_ENDPOINT
+              value: "http://minio:9000"
+            - name: AWS_ACCESS_KEY
+              value: "myuser"
+            - name: AWS_SECRET_KEY
+              value: "mypassword"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: 12-factor-demo-service
+spec:
+  selector:
+    app: 12-factor-demo
+  ports:
+    - protocol: TCP
+      port: 8085
+      targetPort: 8080