diff --git a/README.md b/README.md
deleted file mode 100644
index 641e0d46..00000000
--- a/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Lokal
-
-Lokal is a local business aggregation site helping you to shop locally by providing a one-stop-shop for your local community. Set your profile and start shopping today!
diff --git a/docker-compose.yml b/docker-compose.yml
index e8122736..34d9bfa7 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,25 +5,23 @@ services:
     build:
       context: .
     container_name: lokal
-    environment:
-      DATABASE_URL: "ecto://postgres:postgres@lokal-db/lokal"
-      # generate a random base64 string 64 characters long, preferably not from a website
-      SECRET_KEY_BASE: "change-me-to-something-random-this-is-really-important-change-it"
-    ports:
-      # do not expose this publically!
-      # always host from behind a reverse proxy, with a properly configured certificate
-      - "4000:4000"
     restart: always
+    environment:
+      - DATABASE_URL="ecto://postgres:postgres@lokal-db/lokal"
+      # generate a random base64 string 64 characters long, preferably not from a website
+      - SECRET_KEY_BASE="change-me-to-something-random-this-is-really-important-change-it"
+    expose:
+      - "4000"
     depends_on:
       - lokal-db
 
   lokal-db:
     image: postgres:13
     container_name: lokal-db
-    environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: lokal
     restart: always
+    environment:
+      - POSTGRES_USER="postgres"
+      - POSTGRES_PASSWORD="postgres"
+      - POSTGRES_DB="lokal"
     volumes:
-      - ./data:/var/lib/postgresql/data
\ No newline at end of file
+      - ./data:/var/lib/postgresql/data
diff --git a/readme.md b/readme.md
new file mode 100644
index 00000000..35cb1f1b
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,51 @@
+# Lokal
+
+Lokal is a local business aggregation site helping you to shop locally by
+providing a one-stop-shop for your local community. Set your profile and start
+shopping today!
+
+# Features
+
+- User Registration/Sign in via `phx_gen_auth`
+- `Dockerfile` and example `docker-compose.yml`
+- Automatic migrations in `MIX_ENV=prod` or Docker image
+- JS linting with [standard.js](https://standardjs.com), HEEx linting with
+  [heex_formatter](https://github.com/feliperenan/heex_formatter)
+
+# Installation
+
+1. Clone the repo
+2. Run `mix setup`
+3. Run `mix phx.server` to start the development server
+
+# Configuration
+
+For development, I recommend setting environment variables with
+[direnv](https://direnv.net).
+
+## `MIX_ENV=dev`
+
+In `dev` mode, Lokal will listen for these environment variables on compile.
+
+- `HOST`: External url to generate links with. Set these especially if you're
+  behind a reverse proxy. Defaults to `localhost`.
+- `PORT`: External port for urls. Defaults to `443`.
+- `DATABASE_URL`: Controls the database url to connect to. Defaults to
+  `ecto://postgres:postgres@localhost/lokal_dev`.
+
+## `MIX_ENV=prod`
+
+In `prod` mode (or in the Docker container), Lokal will listen for these environment variables at runtime.
+
+- `HOST`: External url to generate links with. Set these especially if you're
+  behind a reverse proxy. Defaults to `localhost`.
+- `PORT`: Internal port to bind to. Defaults to `4000` and attempts to bind to
+  `0.0.0.0`. Must be reverse proxied!
+- `DATABASE_URL`: Controls the database url to connect to. Defaults to
+  `ecto://postgres:postgres@lokal-db/lokal`.
+- `ECTO_IPV6`: Controls if Ecto should use ipv6 to connect to PostgreSQL.
+  Defaults to `false`.
+- `POOL_SIZE`: Controls the pool size to use with PostgreSQL. Defaults to `10`.
+- `SECRET_KEY_BASE`: Secret key base used to sign cookies. Must be generated
+  with `mix phx.gen.secret` and set for server to start.
+