Merge 012fcb0 into d18358e

.travis.yml

@@ -1,16 +1,27 @@
 language: go
-go:
-- '1.13'
-services:
-- docker
-cache:
-  directories:
-  - "$GOPATH/pkg"
-before_install:
-- go get github.com/mattn/goveralls
-install:
-- make ci/install
-script:
-- make ci/test
-after_success:
-- goveralls -coverprofile=coverage.out -service=travis-ci
+
+go: '1.13'
+
+jobs:
+  include:
+    - stage: test
+      cache:
+        directories:
+          - "$GOPATH/pkg"
+      services:
+      - docker
+      before_install:
+      - go get github.com/mattn/goveralls
+      install:
+      - make ci/install
+      after_success:
+      - goveralls -coverprofile=coverage.out -service=travis-ci
+      script:
+      - make ci/test
+    - stage: deploy
+      on:
+        tags: true
+      services: docker
+      script:
+      - echo "Building images for tag $TRAVIS_TAG..."
+      - push_to_docker.sh

README.md

@@ -13,21 +13,8 @@ Will.IAM solves identity and access management.
 * SSO - Single Sign-On
   * SSO browser handler should save/get to/from localStorage and redirect to requester
 
-  Client redirects to server (browser), server has token in localStorage, redirects back with stored token. No button clicks :) Client should be careful to not log token to other parties (e.g google analytics)
-
-## TODO:
-
-### major
-
-* [ ] Reorganize pkg errors, fill errors/codes.go to keep track of all codes
-* [ ] Revisit errors to return 4xx where it makes sense. (Most places return 500)
-
-### minor
-
-* [ ] Replace %s + err.Error() by %v + err
-* [ ] Replace t.Errorf + return by t.Fatalf where it should stop early
-* [ ] Use api.ErrorResponse in other places
-* [ ] Use api.ListResponse in other places
+  Client redirects to server (browser), server has token in localStorage, redirects back with stored token. No
+  buttonclicks :) Client should be careful to not log token to other parties (e.g google analytics)
 
 ## About RBAC use cases and implementation
 
@@ -37,15 +24,17 @@ Using Maestro, https://github.com/topfreegames/maestro, as an example:
 
 In order to get a list of schedulers, users must have ListSchedulers permission.
 
-Permissions are written in a specific format **{Service}::{OwnershipLevel}::{Action}::{Resource::Hierarchy}**. So, ListSchedulers could be had in a diversity of ways:
+Permissions are written in a specific format **{Service}::{OwnershipLevel}::{Action}::{Resource::Hierarchy}**. So,
+ListSchedulers could be had in a diversity of ways:
 
 Maestro::RO::ListSchedulers::*
 
 Maestro::RL::ListSchedulers::NA::Sniper3D::*
 
 Maestro::RL::ListSchedulers::NA::Sniper3D::sniper3d-game
 
-You'll know more about Will.IAM permissions later. If someone has **Maestro::RL::ListSchedulers::NA::Sniper3D::\***, then Maestro will only respond schedulers under NA::Sniper3D's domain.
+You'll know more about Will.IAM permissions later. If someone has **Maestro::RL::ListSchedulers::NA::Sniper3D::\***,
+then Maestro will only respond schedulers under NA::Sniper3D's domain.
 
 ## Permissions
 
@@ -68,12 +57,14 @@ A verb defined by Will.IAM clients.
 
 ### Resource Hierarchy
 
-Can be complete or open, in the sense that an open hierarchy will probably lead to access to multiple items under a domain.
+Can be complete or open, in the sense that an open hierarchy will probably lead to access to multiple items under a
+domain.
 
 
 ## Client side - /am route
 
-Will.IAM clients should expose a **GET /am** route that will help list actions and resource hierarchies to which the requester has some level os access.
+Will.IAM clients should expose a **GET /am** route that will help list actions and resource hierarchies to which the
+requester has some level os access.
 
 E.g:
 
@@ -85,18 +76,69 @@ E.g:
 
 **GET /am?prefix=ListSchedulers::NA::Sniper3D** -> all schedulers in NA::Sniper3D
 
-To a requester with full access over the client, this means it will list all possible permissions and resources possible to be granted OwnershipLevel::Action to another party.
+To a requester with full access over the client, this means it will list all possible permissions and resources possible
+to be granted OwnershipLevel::Action to another party.
 
 ### Complete permissions
 
-When calling GET /am?prefix={complete-permission-here} your server should respond with the full permission and alias, as it did when autocompleting. This helps Will.IAM request a trustful "alias" to fill permission requests.
+When calling GET /am?prefix={complete-permission-here} your server should respond with the full permission and alias, as
+it did when autocompleting. This helps Will.IAM request a trustful "alias" to fill permission requests.
 
 ### Handling 403
 
 When an unauthorized request is made, a response with `{ "permission": {string}, "alias": {string} }` is expected.
 
+## The CI/CD pipeline
+
+Will.IAM has a very simple CI/CD pipeline in place to help us guarantee that the code has a good quality and to avoid
+broken releases. Currently we use TravisCI to automate the execution of tests, code quality tools and generation and
+publishing of images in our 
+[Docker Hub repository](https://hub.docker.com/r/tfgco/will-iam).
+
+## Issuing new releases
+
+Versioning happens through Git tagging. Every time a tag is created in the "master" branch, a new release will be
+issued, with the associated Docker images pushed to Docker Hub. Each release creates one Docker image with two different
+tags:
+
+* will-iam:<last commit SHA\>
+* will-iam:<X.X.X\>
+
+The current workflow to issue a new release is:
+
+* Open a Pull Request with the code changes.
+
+* After the Pull Request is merged, create a Git tag with the current version and push it to Github. We use
+[Semver](https://semver.org/) as the versioning schema.
+
+* That's it :tada: The corresponding Docker images will be generated automatically :rocket:
+
+But sometimes you may want to issue a bigger release, consisting of many Pull Requests. When that happens,
+the recommended workflow is to open Pull Requests with small code increments. As the Pull Requests are merged and the
+release is ready to be published, send the Git tag to Github and the release will be published. Note that during this
+time the "master" branch may contain breaking changes in the API, so its recommended to proceed with caution when using
+images build from "master".
+
+Suggestions about the CI/CD pipeline are welcome, and we use Github Issues to discuss them.
+
 ## Idea: Permission dependency
 
-A nice-to-have feature would be to declare permission dependencies. It should be expected that **Maestro::RL::EditScheduler::\*** implies following **Maestro::RL::ReadScheduler::\***
+A nice-to-have feature would be to declare permission dependencies. It should be expected that
+**Maestro::RL::EditScheduler::\*** implies following **Maestro::RL::ReadScheduler::\***
+
+One way to do this is to have clients declare them over a Will.IAM endpoint and use this custom entity,
+PermissionDependency, when creating / deleting user|role permissions.
+
+## TODO:
+
+### major
 
-One way to do this is to have clients declare them over a Will.IAM endpoint and use this custom entity, PermissionDependency, when creating / deleting user|role permissions.
+* [ ] Reorganize pkg errors, fill errors/codes.go to keep track of all codes
+* [ ] Revisit errors to return 4xx where it makes sense. (Most places return 500)
+
+### minor
+
+* [ ] Replace %s + err.Error() by %v + err
+* [ ] Replace t.Errorf + return by t.Fatalf where it should stop early
+* [ ] Use api.ErrorResponse in other places
+* [ ] Use api.ListResponse in other places

push_to_docker.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# The image build step occurs only when a build is triggered by a commit being merged into the "master" branch.
+# Given that the "master" branch is protected, the only way to trigger a build from the "master" branch is when a PR
+# is merged into it. This way, we avoid storing images from non-stable branches.
+readonly DOCKER_HUB_REPO='tfgco/will-iam'
+
+docker_tag_exists() {
+    local repo="$1"
+    local tag="$2"
+    curl --silent -flSL "https://index.docker.io/v1/repositories/$repo/tags/$tag" > /dev/null
+}
+
+main() {
+  local last_commit_sha
+  last_commit_sha=$(git rev-parse --short HEAD)
+
+  if docker_tag_exists "$DOCKER_HUB_REPO" "$TRAVIS_TAG"; then
+      echo "An image with the version $TRAVIS_TAG already exists in Docker Hub. Please update your version.txt file and try again."
+      exit 1
+  fi
+
+  docker login -u="$DOCKER_USERNAME" -p="$DOCKER_PASSWORD"
+  docker build -t will-iam .
+  docker tag will-iam "$DOCKER_HUB_REPO:$last_commit_sha"
+  docker tag will-iam "$DOCKER_HUB_REPO:$TRAVIS_TAG"
+  docker push "$DOCKER_HUB_REPO:$last_commit_sha"
+  docker push "$DOCKER_HUB_REPO:$TRAVIS_TAG"
+}
+
+main "$@"