Setup

Setting Up the Github App

First things first, your organization will need to create a new Github App.

Github App Configuration

In your apps permissions configuration, ensure to add read/write to membership
Setup a Callback URL to the frontend of the Just Ask! This should url that the front end compnent will be accessible by.
Setup a description explaining what your version of Just Ask! is used for so that your clients can understand why they are granting access to your Github App
Create and save a client secret, this will be needed to deploy the server
Create and save the github app private key, this will be needed to deploy the server
Install the application on your desired github organizations

Server Configuration

The server expects three files:

config.json
role-mappers.json
github-private-key.pem
cors.json

config.json is a backend descriptor of what installtions this app should expect. Since this application can theoretically be installed anywhere. The server utilizes this file to ensure that only valid changes can be made to the orgs that are configuired from this file.

Sample config.json:

{
  "orgs": [
    "bcgov",
    "bcdevops",
    "patricksimonian",
    "patrick-org-test"
  ],
  "primaryOrg": "patrick-org-test"
}

role-mappers.json is a description of the three main workflows that a user can take when using this application: APPROVER, COLLABORATOR, REQUESTER. Simply put:

Approvers can: automatically invite users into the orgs, approve pending requests
Collaborators can: automatically invite users into the org
Requesters can: ask for an invite that requires approval from an APPROVER

Role mappings can be created from specific org roles in an org or membership in a github team.

{
  "APPROVER": [
    {
      "kind": "OrgRole",
      "role": "admin",
      "name": "bcgov"
    },
    {
      "kind": "GithubTeam",
      "team": "OrgApprovers",
      "organization": "bcgov"
    }
  ],
  "REQUESTER": [null],
  "COLLABORATOR": [
    {
      "kind": "OrgRole",
      "role": "member",
      "organization": "bcgov"
    }
  ]
}

cors.json This config file is not required but will allow you to reach the api from multiple origins. In the case you have configured WEB_URL and cors.json, the cors policy will allow both sets of urls. Take note of the null field. This is a SPECIAL CASE for REQUESTER. If the index 0 position of REQUESTER is null. Than any github user is granted that role implicitly.

[ "https://www.just-ask.com", "https://just-ask.com" ]

The app also takes several environment variables:

APP_ID: required the github application id
CLIENT_SECRET: required the github application client secret
CLIENT_ID: required the github application client id
LOG_LEVEL: defaults to notice but can be escalated to info, debug etc. For more details see log docs
LOG_TIME: defaults to null but can be set to rel or abs. For production installations abs is recommended
PORT: defaults to 3000 when null.
MONGO_URL: required the fully qualified mongo connection string to your mongo database
WEB_URL: required to enable cors, the frontend components’ origin of Just-ask! needs to be set eg WEB_URL=https://just-ask-frontend.com
CONFIG_PATH: production only allows you to change the path of where the api should look for its config files. Only works if NODE_ENV=production
PRIVATE_KEY_PATH: production only allows you to change the path of where the private key is located. This is important in k8s based deployments as typically the API config and the private key would be in a configmap and secret respectively. Only useable when NODE_ENV=production

Web Configuration

The web allows some small configuration to have the Github App look and feel more like your organizations branding. This comes into the form of configuration files:

pallete.json
content.json
config.json
entry.md

pallete.json allows you to adjust the colour scheme of the front end. There is a base scheme and whatever colors you choose to add will override the default ones. It is recommended that you only adjust the primary and secondary colors.

{
  "primary": "#f6f2ff",
  "secondary": "#e07be0"
}

content.json allows you to change the title and add a small logo to the header. Consider using a lightweight png format image for your logo

{
  "brandTitle": "Platform Services' Github Access Management",
  "brandLogo": "path to my png",
  "issuesLink": "path to where you track your issues"
}

If you are concerned with fetching an image from the internet, the brandLogo path can be absolute (/path/to/image.png) and you may mount an image into the run time public folder of the web component as you would these two config files.

config.json is for misc. application configuration.

  // noIndividualOrgRequests: prevents users from individually selecting org requests. They can only request access to all orgs.
  // defaults to false
  {
    "noIndividualOrgRequests": false
  }

entry.md is for a custom entry/homepage. If you do not supply one the default homepage will be used. The custom entry page supports templating (in handlebars format).

# Custom Homepage

The meaning of life and everything is 42. 

[Login here!]()

supported template variables:

login_link: will render the github app login including a randomized state id

The web component also takes a couple of environment variables depending on environment: If you are running the application locally, the environment variables are surfaced through node js and so you will require:

REACT_APP_CLIENT_ID the github app client id
REACT_APP_API_BASE_URL host of the just ask api

If you are running the production image which is a caddy server the environment variables are different:

CLIENT_ID the github app client id
API_BASE_URL host of the just ask api

App Installation

The app is designed using microservice architecture and so the three components (front end, backend, database) must be deployed seperately using your preferred hosting environments. Each component contains a README explaining some considerations for a production installation.