Merge pull request #23 from datatogether/dev-instructions

Add developer instructions

Author: patcon

Diff for: .gitignore

@@ -3,4 +3,4 @@ gin-bin
 coverage
 coverage.txt
 config.*.json
-*.env
+.env

Diff for: Makefile

@@ -0,0 +1,38 @@
+
+DOCKER := $(shell command -v docker 2> /dev/null)
+DOCKER_COMPOSE := $(shell command -v docker-compose 2> /dev/null)
+
+dchecks:
+ifndef DOCKER
+	$(error "Command is not available please install Docker")
+endif
+ifndef DOCKER_COMPOSE
+	$(error "Command is not available please install docker-compose")
+endif
+
+setup: checks ## Docker: setup, build/rebuild app container
+	cp --no-clobber sample.env .env
+	docker-compose build
+
+run: checks ## Docker: run app in container
+	docker-compose up
+
+run-cmd: checks ## Docker: run arbitary command in container, eg. `make drun-cmd go test`
+	docker-compose run coverage $(filter-out $@,$(MAKECMDGOALS))
+
+test: checks ## Docker: run unit tests in container
+	docker-compose run coverage go test
+
+%:
+	@true
+
+.PHONY: help
+
+help:
+	@echo 'Usage: make <command>'
+	@echo
+	@echo 'where <command> is one of the following:'
+	@echo
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help

Diff for: README.md

@@ -33,18 +33,18 @@ It takes a list of urls and associated archiving information, and turns that int
 The output is cached in [`cache.json`](cache.json). Because this is a large file, we provide incremental pieces of the cached tree as a web server. To dynamically calculate coverage completion to can work with the `cache.json` file.
 
 
-## License & Copyright
-
-Copyright (C) 2017 Data Together
-This program is free software: you can redistribute it and/or modify it under
-the terms of the GNU Affero General Public License as published by the Free Software
-Foundation, version 3.0.
+## Routes
 
-This program is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.
+* `/healthcheck` - server status
+* `/repositories` - list all data repositories [:question:][route-repos]
+* `/repositories/:repository_uuid` - get details for a single data repository [:question:][route-repo]
+* `/fulltree` - get full coverage tree of url-based resources
+* `/tree` - get scope-able coverage tree [:question:][route-coverage]
+* `/coverage` - get coverage summary (not currently used)
 
-See the [`LICENSE`](./LICENSE) file for details.
+   [route-repos]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/datatogether/api/master/open_api.yaml#/default/get_repositories
+   [route-repo]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/datatogether/api/master/open_api.yaml#/default/get_repository__id_
+   [route-coverage]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/datatogether/api/master/open_api.yaml#/default/get_coverage
 
 
 ## Getting Involved
@@ -56,11 +56,68 @@ We use GitHub issues for [tracking bugs and feature requests](./issues) and Pull
 
 ## Installation
 
-The easiest way to get going is to use [docker-compose](https://docs.docker.com/compose/install/). Once you have that:
+Running this project can be done either directly on your workstation system, or in a "container" via Docker.
+
+For people comfortable with Docker, or who are excited to learn about it, it can be the best way to get going.
+
+### Docker Install
+
+Running this project via Docker requires:
+
+  * [Docker](https://docs.docker.com/engine/installation/)
+  * [`docker-compose`](https://docs.docker.com/compose/install/)
+
+Running the project in a Docker container should be as simple as:
+
+```
+make setup
+make run
+```
+
+If you get an error about a port "address already in use", you can change the `PORT` environment variable in your local `.env` file.
+
+Barring any changes, you may now visit a JSON endpoint at: `http://localhost:8080/repositories`
+
+### Local System Install
 
-TODO - finish installation instructions
+Running this project directly on your system requires:
+
+  * Go 1.7+
+  * Postgresql
+
+(Setting up these services is outside the scope of this README.)
+
+```
+cd path/to/coverage
+createdb datatogether_coverage
+go build
+go get ./
+# Set a free port on which to serve JSON
+export PORT=8080
+# Your postgresql instance may be running on a different port
+export POSTGRES_DB_URL=postgres://localhost:5432/datatogether_coverage
+$GOPATH/bin/coverage
+```
+
+Barring any changes, you may now visit a JSON endpoint at: `http://localhost:8080/repositories`
 
 
 ## Development
 
-Coming soon.
+Please follow the install instructions above! Inclusion of tests are appreciated!
+
+For a list of all availabe helper commands, just type `make`.
+
+
+## License & Copyright
+
+Copyright (C) 2017 Data Together
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free Software
+Foundation, version 3.0.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.
+
+See the [`LICENSE`](./LICENSE) file for details.

Diff for: docker-compose.yml

@@ -6,13 +6,13 @@ services:
       - .:/go/src/github.com/datatogether/coverage
       - ./sql:/sql
     ports:
-     - 8080:8080
+      - $PORT:$PORT
     networks:
       - back-tier
     depends_on:
       - postgres
     environment:
-      - PORT=8080
+      - PORT=$PORT
       - TLS=false
       - GOLANG_ENV=develop
       - POSTGRES_DB_URL=postgres://postgres@postgres/postgres?sslmode=disable
@@ -23,4 +23,4 @@ services:
       - back-tier
 
 networks:
-  back-tier:
+  back-tier:

Diff for: sample.env

@@ -0,0 +1 @@
+PORT=8080