diff --git a/README.md b/README.md
index 96928f2..3c9bc25 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # teletraan
 
-a static binary-based rootless dockerized web server that is so small, it is effectively braindead, while remaining featureful for most usecases
+a static binary-based rootless dockerized web server that is so small, it is effectively braindead, while remaining featureful for most usecases.
+
+the server runs rootless, read-only, and distroless, making it lighter and more secure than nginx. it serves everything in the /data folder
 
 inspired by busybox httpd.
 
@@ -14,6 +16,40 @@ it has extremely minimal dependencies, so minimal that you can tack on a craploa
 
 it is compiled with ``panic=immediate-abort``.
 
+## example usage
+
+in a compose file, you can use teletraan to run your static site stack:
+
+```yaml
+services:
+    site-with-index.txt:
+        image: codeberg.org/gigirassy/teletraan:latest
+        read_only: true
+        volumes:
+            - "./site:/data"
+        command: "-i" # site made of txt files
+        ports:
+            - "127.0.0.1:9900:3000"
+    spa-matrix-client:
+        image: codeberg.org/gigirassy/teletraan:latest
+        read_only: true
+        volumes:
+            - "./cinny:/data"
+        command: "-s" # single page app
+        ports:
+            - "127.0.0.1:9901:3000"
+    basic-html-site:
+        image: codeberg.org/gigirassy/teletraan:latest
+        read_only: true
+        volumes:
+            - "./basic-html-site:/data"
+        # no command: flags needed!
+        ports:
+            - "127.0.0.1:9904:3000"
+```
+
+and then use external caddy or nginx to reverse proxy the host ports.
+
 ## license
 
 ISC
\ No newline at end of file