Add docs

Signed-off-by: David Pordomingo <[email protected]>

Author: dpordomingo

.github/screenshot.png

@@ -1,49 +1,61 @@
-## Development
+[![Build Status](https://travis-ci.org/src-d/gitbase-playground.svg)](https://travis-ci.org/src-d/gitbase-playground)
+[![codecov.io](https://codecov.io/github/src-d/gitbase-playground/coverage.svg)](https://codecov.io/github/src-d/gitbase-playground)
+![unstable](https://svg-badge.appspot.com/badge/stability/unstable?a)
 
-### Dependencies
+# Gitbase Playground
 
-Launch [bblfshd](https://github.com/bblfsh/bblfshd) and install the drivers. More info in the [bblfshd documentation](https://doc.bblf.sh/user/getting-started.html).
+Web application to query git repositories using SQL. Powered by [gitbase](https://github.com/src-d/gitbase).
 
-```bash
-docker run -d --name bblfshd --privileged -p 9432:9432 -v /var/lib/bblfshd:/var/lib/bblfshd bblfsh/bblfshd
-docker exec -it bblfshd bblfshctl driver install --all
-```
+![Screenshot](.github/screenshot.png?raw=true)
 
-Install [gitbase](https://github.com/src-d/gitbase), populate a repository directory, and start it.
 
-```bash
-go get github.com/src-d/gitbase/...
-cd $GOPATH/src/github.com/src-d/gitbase
-make dependencies
-mkdir repos
-git clone https://github.com/src-d/gitbase-playground.git repos/gitbase-playground
-go run cli/gitbase/main.go server -v --git=repos
-```
+# Usage
 
-### Build
+## Dependencies
 
-```bash
-go build -o gitbase-playground cmd/server/main.go
-```
+The playground will run the queries against a [gitbase](https://github.com/src-d/gitbase) server, and will request UASTs to a [bblfsh](https://doc.bblf.sh/) server; both should be accessible for the playground; you can check its default [configuration values](docs/CONTRIBUTING.md#configuration).
 
-### Run
 
-Use `GITBASEPG_ENV=dev` for extra logs information.
+## Run the Playground
 
-Development:
+You can run the app from a docker image, a released binary or installing and building the project.
 
-```bash
-GITBASEPG_ENV=dev go run cmd/server/main.go
-```
+Once the server is running –with its default values–, it will be accessible through: http://localhost:8080
 
-Built binary:
+Read [more about how to run bblfsh and gitbase dependencies](docs/quickstart.md).
+
+### Run with Docker
 
 ```bash
-GITBASEPG_ENV=dev ./gitbase-playground
+$ docker run -d
+    --publish 8080:8080
+    --link gitbase
+    --env GITBASEPG_ENV=dev
+    --env GITBASEPG_DB_CONNECTION="gitbase@tcp(gitbase:3306)/none?maxAllowedPacket=4194304"
+    --name gitbasePlayground
+    src-d/gitbase-playground:latest
 ```
 
-### Run the Tests
+
+### Run the Binary
+
+Download a binary from our [releases section](https://github.com/src-d/gitbase-playground/releases), and run it:
 
 ```bash
-go test -v server/handler/*
+$ /download/path/gitbase-playground
 ```
+
+
+# Contribute
+
+[Contributions](https://github.com/src-d/gitbase-playground/issues) are more than welcome, if you are interested please take a look to our [Contributing Guidelines](docs/CONTRIBUTING.md). You have more information on how to run it locally for [development purposes here](docs/CONTRIBUTING.md#development).
+
+
+# Code of Conduct
+
+All activities under source{d} projects are governed by the [source{d} code of conduct](https://github.com/src-d/guide/blob/master/.github/CODE_OF_CONDUCT.md).
+
+
+## License
+
+GPL v3.0, see [LICENSE](LICENSE)

README.md

@@ -0,0 +1,73 @@
+# Contribution Guidelines
+
+As all source{d} projects, this project follows the
+[source{d} Contributing Guidelines](https://github.com/src-d/guide/blob/master/engineering/documents/CONTRIBUTING.md).
+
+
+## Additional Contribution Guidelines
+
+In addition to the [source{d} Contributing Guidelines](https://github.com/src-d/guide/blob/master/engineering/documents/CONTRIBUTING.md),
+this project follows the guidelines described below.
+
+
+# Architecture
+
+The application is a go binnary that serves the statics and the API used for the UI.
+
+The statics (`html`, `js` and `css`) are generated by `yarn`, embedded in the go binary using bindata, and served from the binary itself.
+
+There are two main different ways to run the app:
+
+- using released artifacts, as [listed in the README.md](../README.md#run-the-playground)
+- serving the app for development purposes, [building and running it from sources](#run-from-sources)
+
+
+# Configuration
+
+| Variable | Required | Default value | Meaning |
+| -- | -- | -- | -- |
+| `GITBASEPG_HOST` | | `0.0.0.0` | IP address to bind the HTTP server |
+| `GITBASEPG_PORT` | | `8080` | Port address to bind the HTTP server |
+| `GITBASEPG_SERVER_URL` | | `<GITBASEPG_HOST>:<GITBASEPG_PORT>` | URL used to access the application (i.e. public hostname) |
+| `GITBASEPG_DB_CONNECTION` | | `gitbase@tcp(localhost:3306)/none?maxAllowedPacket=4194304` | gitbase connection string |
+| `GITBASEPG_BBLFSHD_URL` | | `127.0.0.1:9432` | Address where bblfsh server is listening |
+| `GITBASEPG_ENV` | | `production` | Sets the log level. Use `dev` to enable debug log messages |
+
+
+# Development
+
+## Requirements
+
+You should already have [Go installed](https://golang.org/doc/install#install), and properly [configured the $GOPATH](https://github.com/golang/go/wiki/SettingGOPATH)
+
+```
+go version; # prints your go version
+go env GOPATH; # prints your $GOPATH path
+```
+
+The project must be under $GOPATH, as required by the Go tooling.
+You should be able to navigate into the source code by running:
+
+```
+cd $GOPATH/src/github.com/src-d/gitbase-playground
+```
+
+You need also [Yarn v1.x.x installed](https://yarnpkg.com/en/docs/install)
+
+```
+yarn --version; # prints your Yarn version
+```
+
+
+## Run from Sources
+
+You need to satisfy all [project requirements](#requirements), and then run:
+
+```bash
+$ go get -d -u github.com/src-d/gitbase-playground/...
+$ cd $GOPATH/github.com/src-d/gitbase-playground
+$ make dependencies
+$ make serve
+```
+
+This will start a server locally, which you can access on [http://localhost:8080](http://localhost:8080)

docs/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Quickstart
+
+## Run bblfsh and gitbase Dependencies
+
+It is recommended to read about `bblfsh` and `gitbase` from its own documentation, but here is a small guide about how to run both easily:
+
+Launch [bblfshd](https://github.com/bblfsh/bblfshd) and install the drivers. More info in the [bblfshd documentation](https://doc.bblf.sh/user/getting-started.html):
+
+```bash
+$ docker run --privileged
+    --publish 9432:9432
+    --volume /var/lib/bblfshd:/var/lib/bblfshd
+    --name bblfsh
+    bblfsh/bblfshd
+$ docker exec -it bblfsh
+    bblfshctl driver install --recommended
+```
+
+[gitbase](https://github.com/src-d/gitbase) will serve git repositories, so it is needed to populate a directory with them:
+
+```bash
+$ mkdir -p ~/gitbase/repos
+$ git clone [email protected]:src-d/go-git-fixtures.git ~/gitbase/repos/go-git-fixtures
+```
+
+Install and run [gitbase](https://github.com/src-d/gitbase):
+
+```bash
+$ docker run
+    --publish 3306:3306
+    --link bblfsh
+    --volume ~/gitbase/repos:/opt/repos
+    --env BBLFSH_ENDPOINT=bblfsh:9432
+    --name gitbase
+    srcd/gitbase:latest
+```
+
+
+## Run gitbase-playground
+
+Once bblfsh and gitbase are running and accessible, you can serve the playground:
+
+```bash
+$ docker run -d
+    --publish 8080:8080
+    --link gitbase
+    --env GITBASEPG_ENV=dev
+    --env GITBASEPG_DB_CONNECTION="gitbase@tcp(gitbase:3306)/none?maxAllowedPacket=4194304"
+    --name gitbase_playground
+   srcd/gitbase-playground:latest
+```
+
+Once the server is running –with its default values–, it will be accessible through: http://localhost:8080
+
+You have more information about the [playground architecture](CONTRIBUTING.md#architecture), [development guides](CONTRIBUTING.md#development) and [configuration options](CONTRIBUTING.md#configuration) in the [CONTRIBUTING.md](CONTRIBUTING.md).
+
+
+## Run a Query
+
+You will find more info about how to run queries using the playground API on the [rest-api guide](rest-api.md)