diff --git a/Makefile b/Makefile
index 20c8bc58c..3817f5f2e 100644
--- a/Makefile
+++ b/Makefile
@@ -1,34 +1,40 @@
+NAME    := unsee
 VERSION := $(shell git describe --tags --always --dirty='-dev')
 
+# Alertmanager instance used when running locally, points to mock data
+ALERTMANAGER_URI := https://raw.githubusercontent.com/prymitive/alertmanager-demo-api/master
+# Listen port when running locally
+PORT := 8080
+
+SOURCES := $(wildcard *.go) $(wildcard */*.go)
+
+.DEFAULT_GOAL := $(NAME)
+
 .build/deps.ok: .gitmodules
 	git submodule update --init --recursive
 	mkdir -p .build
 	touch $@
 
+$(NAME): .build/deps.ok $(SOURCES)
+	go build -ldflags "-X main.version=$(VERSION)"
+
+.PHONY: run
+run: $(NAME)
+	DEBUG=true ALERTMANAGER_URI=$(ALERTMANAGER_URI) PORT=$(PORT) ./unsee
+
 .PHONY: docker-image
-docker-image:
-	docker build --build-arg VERSION=$(VERSION) -t unsee:$(VERSION) .
+docker-image: bindata_assetfs.go
+	docker build --build-arg VERSION=$(VERSION) -t $(NAME):$(VERSION) .
 
-ALERTMANAGER_URI := https://raw.githubusercontent.com/prymitive/alertmanager-demo-api/master
-PORT := 8080
-
-.PHONY: demo
-demo: docker-image
-	@docker rm -f unsee-dev || true
+.PHONY: run-docker
+run-docker: docker-image
+	@docker rm -f $(NAME) || true
 	docker run \
-	    --name unsee-dev \
+	    --name $(NAME) \
 	    -e ALERTMANAGER_URI=$(ALERTMANAGER_URI) \
 	    -e PORT=$(PORT) \
 	    -p $(PORT):$(PORT) \
-	    unsee:$(VERSION)
-
-.PHONY: dev
-dev: .build/deps.ok
-		go build -v -ldflags "-X main.version=${VERSION:-dev}" && \
-		DEBUG=true \
-		ALERTMANAGER_URI=$(ALERTMANAGER_URI) \
-		PORT=$(PORT) \
-		./unsee
+	    $(NAME):$(VERSION)
 
 .PHONY: lint
 lint: .build/deps.ok
@@ -38,6 +44,8 @@ lint: .build/deps.ok
 test: lint
 	@go test -cover `go list ./... | grep -v /vendor/`
 
+#======================== asset helper targets =================================
+
 ASSETS_DIR := $(CURDIR)/static/assets
 CDNJS_PREFIX := https://cdnjs.cloudflare.com/ajax/libs
 
diff --git a/README.md b/README.md
index c12ca7843..d25b2c685 100644
--- a/README.md
+++ b/README.md
@@ -9,15 +9,35 @@ to alert data, therefore safe to be accessed by wider audience.
 
 ## Building and running
 
-### Running in dev mode
+### Building from source
 
-Requires Go.
+To clone git repo and build the binary yourself run:
 
-    make dev
+    git clone https://github.com/cloudflare/unsee $GOPATH/src/github.com/cloudflare/unsee
+    cd $GOPATH/src/github.com/cloudflare/unsee
+    make
 
-Will compile unsee and run the binary (not using Docker), by default will use
-same port and Alertmanager URI as demo mode. This is intended for local
-development.
+`unsee` binary will be compiled in project directory.
+
+### Running
+
+`unsee` is configured via environment variables or command line flags.
+Environment variable `ALERTMANAGER_URI` or cli flag `-alertmanager.uri` is the
+only option required to run. See `Environment variables` section below for the
+full list of supported environment variables. Examples:
+
+    ALERTMANAGER_URI=https://alertmanager.example.com unsee
+    unsee -alertmanager.uri https://alertmanager.example.com
+
+There is a make target which will compile and run unsee:
+
+    make run
+
+By default it will listen on port `8080` and Alertmanager mock data will be
+used, to override Alertmanager URI set `ALERTMANAGER_URI` and/or `PORT` make
+variables. Example:
+
+    make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run
 
 ### Build a Docker image
 
@@ -25,17 +45,14 @@ development.
 
 This will build a Docker image from sources.
 
-### Running the Docker image in demo mode
+### Running the Docker image
 
-    make demo
+    make run-docker
 
-Will run locally build Docker image. This is intended for testing build Docker
-images or checking unsee functionality.
-By default unsee will listen on port `8080` and Alertmanager mock data will be
-used, to override Alertmanager URI set `ALERTMANAGER_URI` and/or `PORT` make
-variables. Example:
+Will run locally built Docker image. Same defaults and override variables
+apply as with `make run`. Example:
 
-    make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run
+    make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run-docker
 
 ### Environment variables
 
@@ -172,6 +189,14 @@ This option can also be set using `-jira.regex` flag. Example:
 
 This variable is optional and default is not set (no rule will be applied).
 
+#### PORT
+
+HTTP port to listen on. Example:
+
+    PORT=8000
+
+Default is `8080`.
+
 #### SENTRY_DSN
 
 DSN for [Sentry](https://sentry.io) integration in Go. See