fabric8-cluster

README

= OpenShift.io Cluster Managment service
:toc:
:toc-placement: preamble
:sectnums:
:experimental:

image:https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-cluster-build-master-push-client[Jenkins,link="https://ci.centos.org/view/Devtools/job/devtools-fabric8-cluster-build-master-push-client/lastBuild/"]
image:https://goreportcard.com/badge/github.com/fabric8-services/fabric8-cluster[Go Report Card, link="https://goreportcard.com/report/github.com/fabric8-services/fabric8-cluster"]
image:https://godoc.org/github.com/fabric8-services/fabric8-cluster?status.png[GoDoc,link="https://godoc.org/github.com/fabric8-services/fabric8-cluster"]
image:https://codecov.io/gh/fabric8-services/fabric8-cluster/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/fabric8-services/fabric8-cluster"]

== Building from source [[building]]

The following guide is mainly targeted towards a Linux or Mac OSX development
machine.

=== Prerequisites [[prerequisites]]

You need to install:

* `go` (>= v1.8)
* `git`
* `mercurial`
* `make`

==== Check your Go version [[check-go-version]]

Run the following command to find out your Go version.

----
$ go version
----

*You must at least have Go version 1.8.*

See <<fetch-dependencies>> to see an explanaition on how we deal with
dependencies.

==== Install dep [[dep-setup]]

This project uses https://github.com/golang/dep[dep] as a package manager for Go.
Running the `make deps` command will install `dep` in `$GOPATH/bin` if it's not already available on your system.

=== Get the code [[get-the-code]]

Assuming you have Go installed and configured (have `$GOPATH` setup) here is
how to build.

Check out the code

----
$ git clone https://github.com/fabric8-services/fabric8-cluster $GOPATH/src/github.com/fabric8-services/fabric8-cluster
----

=== Build [[build]]

Like most other projects, this one depends on various other projects that need
to be downloaded.

We also generate some code from design files that shall make it into our
final artifacts.

To fetch the dependencies, generate code and finally build the project you can
type `make` in a freshly clone repository of this project.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make
----

==== Special make targets

There is no need to fetch the dependencies, or re-generate code every time you
want to compile. That's why we offer special `make` targets for these topics:

 * <<fetch-dependencies>>
 * <<generate-code>>
 * <<build>>
 * <<clean>>
 * <<test>>
 * <<coverage>>

===== Fetch dependencies [[fetch-dependencies]]

This will download all the dependencies for this project inside a directory
called `vendor`. This way we can ensure that every developer and our CI system
is using the same version.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make deps
----

For dependency management of `go` packages we use https://github.com/golang/dep[`dep`].

The file `Gopkg.toml` contains all dependencies. If you want to understand the format for this file, look link:https://golang.github.io/dep/docs/Gopkg.toml.html[here].

===== Generate GOA sources [[generate-code]]

You need to run this command if you just checked out the code and later if
you've modified the designs.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make generate
----

===== Build [[build]]

If you want to just build the Auth server and client, run `make build`.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make build
----

===== Clean [[clean]]

This removes all downloaded dependencies, all generated code and compiled
artifacts.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make clean
----

===== Tests [[test]]

Here's how to run all available tests. All tests will check all Go packages
except those in the `vendor/` directory.
Make sure you have docker and docker-compose available.

Setting up test environment - `make integration-test-env-prepare`

Tear test environment down - `make integration-test-env-tear-down`

[horizontal]
unit-tests::
Unit tests have the minimum requirement on time and environment setup.
+
----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make test-unit
----

integration-tests::
Integration tests demand more setup (i.e. the PostgreSQL DB must be already
running) and probably time. We recommend that you use `docker-compose up -d db`.
+
----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make test-integration
----

all::
To run both, the unit and the integration tests you can run
+
----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make test-all
----

By default, test data is removed from the database after each test, unless the `F8_CLEAN_TEST_DATA` environment variable is set to `false`. This can be particularily useful to run queries on the test data after a test failure, in order to understand why the result did not match the expectations.

Also, all SQL queries can be displayed in the output if the `F8_ENABLE_DB_LOGS` environment variable is set to `true. Beware that this can be very verbose, though ;)

===== Coverage [[coverage]]

To visualize the coverage of unit, integration, or all tests you can run these
commands:

 * `$ make coverage-unit`
 * `$ make coverage-integration`
 * `$ make coverage-all`

NOTE: If the tests (see <<test>>) have not yet run, or if the sources have changed
since the last time the tests ran, they will be re-run to produce up to date
coverage profiles.

Each of the above tests (see <<test>>) produces a coverage profile by default.
Those coverage files are available under

----
tmp/coverage/<package>/coverage.<test>.mode-<mode>
----

Here's how the <placeholders> expand

[horizontal]
`<package>`::
something like `github.com/fabric8-services/fabric8-cluster/models`

`<test>`::
`unit` or `integration`

`<mode>`::
Sets the mode for coverage analysis for the packages being tested.
Possible values for `<mode>` are *set* (the default), *count*, or *atomic* and
they directly relate to the output of `go test --help`.
 * *set*: bool: does this statement run?
 * *count*: int: how many times does this statement run?
 * *atomic*: int: count, but correct in multithreaded tests; significantly more
   expensive.

In addition to all individual coverage information for each package, we also
create three more files:

[horizontal]
`tmp/coverage.unit.mode-<mode>`::
This file collects all the coverage profiles for all *unit* tests.

`tmp/coverage.integration.mode-<mode>`::
This file collects all the coverage profiles for all *integration* tests.

`tmp/coverage.mode-<mode>`::
This file is the merge result of the two afore mentioned files and thus gives
coverage information for all tests.

==== Development

These files and directories are generated and should not be edited:

 * `./app/`
 * `./client/`
 * `./swagger/`
 * `./tool/`

== Developer setup

Start up dependent docker services using `docker-compose` and runs auto reload on source change tool `fresh`.

----
$ cd $GOPATH/src/github.com/fabric8-services/fabric8-cluster
$ make dev
----

The above steps start the API Server on port 8087.

Test out the build by executing CLI commands in a different terminal.

NOTE: The CLI needs the API Server which was started on executing `make dev`  to be up and running. Please do not kill the process. Alternatively if you haven't run `make dev` you could just start the server by running `./bin/cluster`.

=== Reset Database

The database are kept in a docker container that gets reused between restarts. Thus restarts will not clear out the database.

To clear out the database kill the database like this:

----
$ docker kill fabric8cluster_db_1 && docker rm fabric8cluster_db_1
----

In case you have mulitple `fabric8*` running use `docker ps` to locate the container name.

==== Code formatting

To check if the code is properly formatted run:
```
$ make check-go-format
```

To format the code:
```
$ make format-go-code
```