Fabric8 Auth

Table of Contents

• 1. Documentation
• 2. Building from source
  • 2.1. Prerequisites
  • 2.2. Get the code
  • 2.3. Build
• 3. Developer setup
  • 3.1. Reset Database
• 4. Rapid development on Minishift

1. Documentation

You can find both reference documentation and developer documentation in the following location:

fabric8-auth docs.

2. Building from source

The following guide is mainly targeted towards a Linux or Mac OSX development machine. If you are on Windows, we recommend to take a look at Getting started with fabric8-auth development on Windows.

2.1. Prerequisites

You need to install:

• go (>= v1.8)

• git

• mercurial

• make

2.1.1. Check your 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.

2.1.2. Install dep

This project uses 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.

2.2. 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-auth $GOPATH/src/github.com/fabric8-services/fabric8-auth

2.3. 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-auth
$ make

If you are getting the following error

[ERROR]	Failed to set references: Unable to update checked out version (Skip to cleanup)
make: *** [vendor] Error 1

Try out this

$ glide cache-clear
$ make clean deps
$ make build

2.3.1. 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 GOA sources

• Build

• Clean

• Tests

• Coverage

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-auth
$ 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 here.

Generate GOA sources

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-auth
$ make generate

Build

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

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

Clean

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

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

Tests

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

unit-tests	Unit tests have the minimum requirement on time and environment setup. $ cd $GOPATH/src/github.com/fabric8-services/fabric8-auth $ 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-auth $ make test-integration
all	To run both, the unit and the integration tests you can run $ cd $GOPATH/src/github.com/fabric8-services/fabric8-auth $ make test-all

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 Tests) 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 Tests) 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

<package>	something like github.com/fabric8-services/fabric8-auth/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:

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.

2.3.2. Development

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

• ./app/

• ./client/

• ./swagger/

• ./tool/cli/

3. 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-auth
$ make dev

The above steps start the API Server on port 8089.

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/auth.

Generate a token for future use.

./bin/auth-cli generate token -H localhost:8089 --pp

You should get Token in response, save this token in your favourite editor as you need to use this token for POST API calls

3.1. 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 fabric8auth_db_1 && docker rm fabric8auth_db_1

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

4. Rapid development on Minishift

See the following README in the minishift directory for instructions on running fabric8-auth in minishift:

Minishift README.