diff --git a/README.md b/README.md
new file mode 100644
index 0000000..56a8682
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# docker-compose-m4
+
+preprocess docker-compose.yml with m4
+
+This is a simple script that preprocesses your docker-compose.yml file with the m4 preprocessor.
+
+## Installation
+
+```
+# make install
+```
+
+## Usage
+
+Let's say we have a docker-compose.yml file like following. We would like to store it in a git repository, but we don't want to show people the postgres password.
+
+One option would be to use [secrets](https://docs.docker.com/compose/use-secrets/), but that won't work if one of the containers doesn't support reading the password from a file.
+We would need a preprocessor for that.
+
+`docker-compose.yml`
+```yaml
+version: '3'
+
+services:
+  db:
+    image: postgres:15
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=joplin
+      - POSTGRES_DB=joplin
+      - POSTGRES_PASSWORD=passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword
+  app:
+    image: joplin/server:latest
+    depends_on:
+      - db
+    ports:
+      - "127.0.0.1:22300:22300"
+    restart: unless-stopped
+    environment:
+      - APP_PORT=22300
+      - APP_BASE_URL=https://joplin.example.com/
+      - DB_CLIENT=pg
+      - POSTGRES_CONNECTION_STRING=postgresql://joplin:passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword@db/joplin?sslmode=disable
+```
+
+1. Let's rename `docker-compose.yml` to `docker-compose.yml.m4`
+
+```
+mv docker-compose.yml docker-compose.yml.m4
+```
+
+2. Move the password to a separate text file next to `docker-compose.yml.m4` and modify `docker-compose.yml.m4` to read the password from that file.
+
+`pgpass.txt`
+```
+passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword
+```
+
+We can use the `iinclude()` function from docker-compose-m4 to include a file and strip newlines.
+
+`docker-compose.yml.m4`
+```diff
+version: '3'
+
+services:
+  db:
+    image: postgres:15
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=joplin
+      - POSTGRES_DB=joplin
+-      - POSTGRES_PASSWORD=passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword
++      - POSTGRES_PASSWORD=iinclude(pgpass.txt)
+  app:
+    image: joplin/server:latest
+    depends_on:
+      - db
+    ports:
+      - "127.0.0.1:22300:22300"
+    restart: unless-stopped
+    environment:
+      - APP_PORT=22300
+      - APP_BASE_URL=https://joplin.example.com/
+      - DB_CLIENT=pg
+-      - POSTGRES_CONNECTION_STRING=postgresql://joplin:passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword@db/joplin?sslmode=disable
++      - POSTGRES_CONNECTION_STRING=postgresql://joplin:iinclude(pgpass.txt)@db/joplin?sslmode=disable
+```
+
+Finally run the preprocessor to generate the docker-compose.yml file.
+```
+docker-compose-m4
+```
+
+`docker-compose.yml` is now created and ready to be used.
+
+`docker-compose.yml`
+```yaml
+# DO NOT EDIT THIS FILE
+# it has been autogenerated from docker-compose.yml.m4, edit that file instead and then run docker-compose-m4
+
+version: '3'
+
+services:
+  db:
+    image: postgres:15
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=joplin
+      - POSTGRES_DB=joplin
+      - POSTGRES_PASSWORD=passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword
+  app:
+    image: joplin/server:latest
+    depends_on:
+      - db
+    ports:
+      - "127.0.0.1:22300:22300"
+    restart: unless-stopped
+    environment:
+      - APP_PORT=22300
+      - APP_BASE_URL=https://joplin.example.com/
+      - DB_CLIENT=pg
+      - POSTGRES_CONNECTION_STRING=postgresql://joplin:passwordpasswordpasswordpasswordpasswordpasswordpasswordpassword@db/joplin?sslmode=disable
+```