diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..0953a68
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,42 @@
+# Demo Laravel app under docker / docker-compose
+
+This is just an example of brining up a composer based project under docker-compose. Not yet adapted for AWS/RDS/EBS/etc, pulls the postgres image and hosts it's own DB just to demo.
+
+## Procedure for running
+
+### Environment Variables
+
+Docker-compose will look for and copy any values found for the following ENV variables:
+
+  + DB_CONNECTION
+  + DB_HOST
+  + DB_PORT
+  + DB_DATABASE
+  + DB_USERNAME
+  + DB_PASSWORD
+  + POSTGRES_USER
+
+For development environments I usually use direnv which will publish values found in a `.envrc` file in the same dir. These could be set by Jenkins as part of a CI/CD deploy.
+
+### Prepare storage
+
+The current `docker-compose.yml` mounts the laravel storage dir from the project working dir. You'll need to create the directory structure Laravel expects or it won't be able to write session files, logs, compiled view templates etc. Run something like: `mkdir -pv ./storage/laravel/framework/{cache,sessions,views}`. This would probably be better as a named volume, but that'd less straightforward to get up and running.
+
+### Actually Running
+
+  + Create the DB instance  
+    `docker-compose up -d db`
+  + Check that worked  
+    `docker-compose ps db` this should report something like:  
+
+	```
+	     Name                       Command              State    Ports  
+	-------------------------------------------------------------------------  
+	laravel_demo_db_1   docker-entrypoint.sh postgres   Up      5432/tcp  
+	```
+
+  + Run migrations  
+    `docker-compose run app ./artisan migrate`
+  + Start the app  
+	`docker-compose up -d`
+