almighty-core

== ALMighty Core

image:https://goreportcard.com/badge/github.com/almighty/almighty-core[Go Report Card, link="https://goreportcard.com/report/github.com/almighty/almighty-core"]
image:https://godoc.org/github.com/almighty/almighty-core?status.png[GoDoc,link="https://godoc.org/github.com/almighty/almighty-core"]

== Building from source [[building]]

=== Prerequisites [[prerequisites]]

You need to install `go` (>= v1.5) and `git` and `mercurial`.

==== 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.6. Our code uses a code generation
tool called goa and it doesn't play nice together with Go 1.5.*

Ensure the environment variable `GO15VENDOREXPERIMENT`
is set, for example by running `export GO15VENDOREXPERIMENT=1`.
In Go `1.6` it is enabled by default and in Go `1.7` it is always enabled
without the ability to turn it off.

If set, the link:https://github.com/golang/go/wiki/PackageManagementTools#go15vendorexperiment[`GO15VENDOREXPERIMENT`]
variable tells `go` to look for dependencies not only in the `GOPATH` (as usual)
but also in a `vendor` directory located in the source directory.

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

==== Install glide [[glide-setup]]

This project uses link:https://glide.sh/[glide] as a package manager for Go.

To install glide, go to the
link:https://github.com/Masterminds/glide/releases[release page] and download
the newest binary for your operating system.

Unpack the archive that you've downloaded and place the `glide` executable
somewhere so that it is in your `PATH`.

To check if everything is working, type `glide --version` in a terminal.

----
$ glide --version
glide version v0.11.0
----

Try to use at least version `0.11.0` as we haven't tested another version.

=== 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/almighty/almighty-core $GOPATH/src/github.com/almighty/almighty-core
----

=== 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/almighty/almighty-core
$ 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>>

===== 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/almighty/almighty-core
$ make deps
----

For dependency management of `go` packages we use `glide`.
The file `glide.yaml` contains all dependencies.
It is not suggested that you edit the file by hand but if you want to
understand the format for this file, look https://glide.readthedocs.io/en/latest/glide.yaml/[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/almighty/almighty-core
$ make generate
----

===== Build [[build]]

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

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make build
----

===== Clean [[clean]]

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

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make clean
----

===== Tests [[test]]

This runs all unit-tests

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make test-unit
----

This runs all integration tests (you need to have a postgres database running for this to work)

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make test-integration
----

To run all above tests you can run

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make test-all
----

==== Development

Only files `./*.go` and `./design/*.go` should be edited.

These files and directory are generated:

 * `./app/`
 * `./assets/js/`
 * `./client/`
 * `./models/`
 * `./swagger/`
 * `./tool/cli/`
 * `./bindata_asstfs.go`

== Developer setup

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

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make dev
----

== OpenShift setup

TBD