Merge pull request #172 from carlosms/improve-docs

Rearrange and improve docs

README.md

@@ -1,62 +1,88 @@
 [![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)
 
 # Gitbase Playground
 
-Web application to query git repositories using SQL. Powered by [gitbase](https://github.com/src-d/gitbase).
+Web application to query Git repositories using SQL. Powered by [gitbase](https://github.com/src-d/gitbase), it allows to perform SQL queries on the Git history and the [Universal AST](https://doc.bblf.sh/) of the code itself.
 
 ![Screenshot](.github/screenshot.png?raw=true)
 
-
 # Usage
 
-## Dependencies
+## With Docker Compose
+
+The easiest way to run Gitbase Playground and its dependencies is using [Docker Compose](https://docs.docker.com/compose/install/).
 
-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).
+The first step is to populate a directory with some Git repositories to be served by gitbase before running it. For example:
 
+```bash
+$ mkdir $HOME/repos
+$ cd $HOME/repos
+$ git clone git@github.com:src-d/gitbase.git
+$ git clone git@github.com:bblfsh/bblfshd.git
+$ git clone git@github.com:src-d/gitbase-playground.git
+```
 
-## Run the Playground
+Next you will need to download the `docker-compose.yml` file from this repository and run `docker-compose`. This tool will run three different containers: the playground frontend itself, gitbase, and bblfshd. To kill the running containers use `Ctrl+C`.
+
+```bash
+$ wget https://raw.githubusercontent.com/src-d/gitbase-playground/master/docker-compose.yml
+$ docker-compose pull
+$ GITBASEPG_REPOS_FOLDER=$HOME/repos docker-compose up --force-recreate
+```
 
-You can run the app from a docker image, a released binary or installing and building the project.
+The server should be now available at [http://localhost:8080](http://localhost:8080).
 
-Once the server is running –with its default values–, it will be accessible through: http://localhost:8080
+## Without Docker Compose
 
-Read [more about how to run bblfsh and gitbase dependencies](docs/quickstart.md).
+The playground will run the queries against a [gitbase](https://docs.sourced.tech/gitbase) server, and will request UASTs to a [bblfsh](https://doc.bblf.sh/) server. Make sure both are properly configured.
 
-### Run with Docker
+Then you can choose to run the Gitbase Playground either as a docker container, or as a binary.
+
+### As a Docker
 
 ```bash
 $ docker pull srcd/gitbase-playground:latest
 $ docker run -d \
     --publish 8080:8080 \
-    --link gitbase \
-    --env GITBASEPG_ENV=dev \
-    --env GITBASEPG_DB_CONNECTION="root@tcp(gitbase:3306)/none?maxAllowedPacket=4194304" \
-    --name gitbasePlayground \
+    --env GITBASEPG_DB_CONNECTION="root@tcp(<gitbase-ip>:3306)/none" \
+    --env GITBASEPG_BBLFSH_SERVER_URL="<bblfshd-ip>:9432" \
     srcd/gitbase-playground:latest
 ```
 
+### As a Binary
 
-### Run the Binary
-
-Download a binary from our [releases section](https://github.com/src-d/gitbase-playground/releases), and run it:
+Download the binary from our [releases section](https://github.com/src-d/gitbase-playground/releases), and run it:
 
 ```bash
-$ /download/path/gitbase-playground
+$ export GITBASEPG_DB_CONNECTION="root@tcp(<gitbase-ip>:3306)/none"
+$ export GITBASEPG_BBLFSH_SERVER_URL="<bblfshd-ip>:9432"
+$ ./gitbase-playground
 ```
 
+# Configuration
 
-# Contribute
+Any of the previous execution methods accept configuration through the following environment variables.
 
-[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).
+| Variable | Default value | Meaning |
+| -- | -- | -- |
+| `GITBASEPG_HOST` | `0.0.0.0` | IP address to bind the HTTP server |
+| `GITBASEPG_PORT` | `8080` | Port to bind the HTTP server |
+| `GITBASEPG_SERVER_URL` | | URL used to access the application in the form `HOSTNAME[:PORT]`. Leave it unset to allow connections from any proxy or public address |
+| `GITBASEPG_DB_CONNECTION` | `root@tcp(localhost:3306)/none?maxAllowedPacket=4194304` | gitbase connection string |
+| `GITBASEPG_BBLFSH_SERVER_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 |
+| `GITBASEPG_SELECT_LIMIT` | `100` | Default `LIMIT` forced on all the SQL queries done from the UI |
+| `GITBASEPG_FOOTER_HTML` | | Allows to add any custom html to the page footer. It must be a string encoded in base64. Use it, for example, to add your analytics tracking code snippet  |
 
+# 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). There you will also find information on how to build and run the project from sources.
 
 # 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
+# License
 
 GPL v3.0, see [LICENSE](LICENSE)

docs/CONTRIBUTING.md

@@ -1,89 +1,158 @@
-# Contribution Guidelines
+# Gitbase Playground 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).
 
+In addition to those guidelines, this document describes how to build and run the application for development purposes.
 
-## Additional Contribution Guidelines
+# Requirements
 
-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.
+Refer to the main [README](../README.md) for the common requirements and configuration environment variables.
 
+Make sure you also satisfy these requirements:
+- [Install Go](https://golang.org/doc/install) and [configure the $GOPATH](https://github.com/golang/go/wiki/SettingGOPATH).
+- This project should be cloned in `$GOPATH/github.com/src-d/gitbase-playground`.
+- Install [Node.js](https://nodejs.org) and [Yarn](https://yarnpkg.com/en/docs/install).
 
-# Architecture
+## Run bblfsh and gitbase Dependencies
+
+As with a normal deployment, if you don't use Docker Compose you will need to configure a [gitbase](https://docs.sourced.tech/gitbase) server, and a [bblfsh](https://doc.bblf.sh/) server. It is recommended to read their documentation, but here is a quick guide on how to run both as docker containers.
+
+Launch bblfshd and install the required drivers:
+
+```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
+```
 
-The application is a go binnary that serves the statics and the API used for the UI.
+gitbase will serve Git repositories, so you will need to to populate a directory with them:
 
-The statics (`html`, `js` and `css`) are generated by `yarn`, embedded in the go binary using bindata, and served from the binary itself.
+```bash
+$ mkdir $HOME/repos
+$ cd $HOME/repos
+$ git clone git@github.com:src-d/gitbase.git
+$ git clone git@github.com:bblfsh/bblfshd.git
+$ git clone git@github.com:src-d/gitbase-playground.git
+```
 
-There are two main different ways to run the app:
+Launch gitbase:
+
+```bash
+$ docker run \
+    --publish 3306:3306 \
+    --link bblfsh \
+    --volume $HOME/repos:/opt/repos \
+    --env BBLFSH_ENDPOINT=bblfsh:9432 \
+    --name gitbase \
+    srcd/gitbase
+```
 
-- 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)
+# Architecture
 
+The application is a Go binary that serves the static files and the API used for the UI.
 
-# Configuration
+The static files (`html`, `js`, and `css`) are generated by `yarn`, embedded in the Go binary using `go-bindata`, and served from the binary itself.
 
-| 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` | | `root@tcp(localhost:3306)/none?maxAllowedPacket=4194304` | gitbase connection string |
-| `GITBASEPG_BBLFSH_SERVER_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 |
-| `FOOTER_HTML` | | | Allows to add any custom html to the page footer. It must be encoded in base64 |
+# API
 
+The backend API is documented in the [rest API guide](rest-api.md)
 
 # Development
 
-## Requirements
+Each one of the following sections describes an alternative method to run the project from sources. You may use the one that suits your needs.
 
-You should already have [Go installed](https://golang.org/doc/install#install), and properly [configured the $GOPATH](https://github.com/golang/go/wiki/SettingGOPATH)
+They all require the project is cloned into your `$GOPATH`.
 
+```bash
+$ go get -d -u github.com/src-d/gitbase-playground/...
+$ cd $GOPATH/github.com/src-d/gitbase-playground
 ```
-go version; # prints your go version
-go env GOPATH; # prints your $GOPATH path
+
+## Run from Sources
+
+The following command will build the frontend and serve it from the Go backend:
+
+```bash
+$ make serve
 ```
 
-The project must be under $GOPATH, as required by the Go tooling.
-You should be able to navigate into the source code by running:
+This will start a server locally, which you can access at [http://localhost:8080](http://localhost:8080).
+
+## Run Using webpack Hot Module Replacement
+
+Instead of rebuilding the frontend and restarting the backend every time you do a change, you may instead run the backend to provide the API, and use webpack to serve the frontend.
 
+In one terminal run the Go backend:
+
+```bash
+$ GITBASEPG_ENV=dev go run cmd/gitbase-playground/main.go
 ```
-cd $GOPATH/src/github.com/src-d/gitbase-playground
+
+In another terminal, run the frontend:
+```bash
+$ yarn --cwd frontend install
+$ yarn --cwd frontend start
 ```
 
-You need also [Yarn v1.x.x installed](https://yarnpkg.com/en/docs/install)
+## Run with Docker Compose from Sources
+
+The file `docker-compose.build.yml` overrides the default compose file. Using it a new docker image, `gitbase-playground-dev`, will be created from the current sources.
 
+```bash
+$ make dependencies
+$ make packages
+$ GITBASEPG_REPOS_FOLDER=$HOME/repos docker-compose \
+    -f docker-compose.yml -f docker-compose.build.yml \
+    up --force-recreate --build
 ```
-yarn --version; # prints your Yarn version
+
+For convenience you may run the same commands with:
+
+```bash
+$ make compose-serve
 ```
 
+## Build a Docker Container
 
-## Run from Sources
+These commands will build a stand-alone docker image, that will require external gitbase and bblfshd servers.
 
-You need to satisfy all [project requirements](#requirements), and then run:
+```bash
+$ make dependencies
+$ make packages
+$ make docker-build
+```
+
+# Testing
+
+## Lint
+
+Use `make lint` to make sure the code follows the project's coding style.
 
 ```bash
-$ go get -d -u github.com/src-d/gitbase-playground/...
-$ cd $GOPATH/github.com/src-d/gitbase-playground
-$ make serve
+$ make lint
 ```
 
-This will start a server locally, which you can access on [http://localhost:8080](http://localhost:8080)
+## Unit Tests
 
+The command `make test` will run JavaScript and Go tests.
+
+```bash
+$ make test
+```
 
 ## Integration Tests
 
-The integration tests require that `gitbase` and `bblfshd` are running and available for the playground.
+Use the `GITBASEPG_INTEGRATION_TESTS=true` environment variable with the same `make test` command.
+
+The integration tests require that `gitbase` and `bblfshd` are running and reachable. See the [Requirements section](#requirements) above for more details.
 
 It is also required to configure the running `gitbase` to serve a copy of the `https://github.com/src-d/gitbase-playground` repository.
 
 ```bash
-$ docker run -d --name bblfshd --privileged -p "9432:9432" bblfsh/bblfshd
-$ docker exec -it bblfshd bblfshctl driver install --recommended
-$ mkdir $HOME/repos
-$ git clone https://github.com/src-d/gitbase-playground.git $HOME/repos/gitbase-playground
-$ docker run -d --name gitbase -p "3306:3306" -e "BBLFSH_ENDPOINT=bblfshd:9432" --volume $HOME/repos:/opt/repos --link bblfshd srcd/gitbase
 $ GITBASEPG_INTEGRATION_TESTS=true make test
 ```