How to setup Holocron

Requirements

• Postgres database service.

SSO setup

In order to utilize access controls, Holocron requires an SSO service to be configured. Any request to the Holocron API will need a JSON Web Token (JWT) attached as an Authorization header, using the Bearer <token> format. As such, you will need to set Holocron behind some form of reverse proxy, service mesh, or similar.

Currently, Holocron has only been tested to work with Keycloak, but any other form of SSO should work if it can be configured similarly to below.

Administrators

To set up Holocron administrators, you must create a group. To do this, you’ll need to specify the following information using environment variables:

1. The name of the group should be provided using the SSO_ADMIN_GROUP environment variable.
2. You should also specify where to find key information about the user from the decoded JWT. This information can be defined using two environment variables:
3. SSO_GROUPS_KEY for group information.
4. SSO_USERNAME_KEY for the username.

If you have enabled the experimental feature COST_METRICS, create a separate group for individuals who need access to pay data. You can assign this group by using the SSO_LEADERSHIP_GROUP environment variable.

App access control

If enabled, Holocron has the following access control groups and roles:

1. Admin: This role has all the global rights to the app with the exception of seeing and updating pay data. In order to obtain this role, user must be in the SSO_ADMIN_GROUP group (for more information on this group consult the Collector Environmental Variables section).
2. OrgLeadership: If the experimental feature COST_METRICS is enabled, this role gives the permission to view and update pay data. In order to obtain this role, user must be in the SSO_LEADERSHIP_GROUP group (for more information on this group consult the Collector Environmental Variables section).
3. OrgAdmin (Organization Admin): This role gives the permission to view metrics of, update, and delete a specific organization. It also gives rights to create, view metrics, update, and delete teams and value streams within that same organization. This role is managed internally by the API.
4. VSAdmin (Value Stream Admin): This role gives the permission to view metrics of, update, and delete a specific value stream. It also gives rights to create, view metrics, update, and delete teams within that same value stream. This role is managed internally by the API.
5. TeamAdmin (Team Admin): This role gives the permission to view metrics of, update, and delete a team. This role is managed internally by the API.

More on these roles access control is show in the matrix below.

Please be aware that the following roles: Organization Leader, Organization Admin, Value Stream Admin, and Team Admin, are granted and relevant only within the confines of their respective organizations.

Y ¹ user must also be admin of organization

Y ² user must also be admin of value stream

Y ³ user must also be admin of Organization which contains value stream

Y ⁴ user must also be admin of Team

Y ⁵ user must also be admin of Value stream which contains Team

Permissions	Admin + OrgLeadership	Admin	Org admin	Org admin + OrgLeadership	VS Admin	VS Admin + OrgLeadership	Team Admin	Team Admin + OrgLeadership
Create Organization	Y	Y
Read Organization Metrics	Y	Y	Y 1	Y 1
Read Organization Cost Metrics	Y			Y 1
Update Organization	Y	Y	Y 1	Y 1
Delete Organization	Y	Y	Y 1	Y 1
Create Value Stream	Y	Y	Y	Y
Read Value Stream Metrics	Y	Y	Y 1	Y 1	Y 2	Y 2
Read Value Stream Cost Metrics	Y			Y 3		Y 2
Update Value Stream	Y	Y	Y 3	Y 3	Y 2	Y 2
Delete Value Stream	Y	Y	Y 3	Y 3	Y 2	Y 2
Create Team	Y	Y	Y	Y	Y	Y
Read Team Metrics	Y	Y	Y 1	Y 1	Y 5	Y 5	Y 4	Y 4
Read Team Cost Metrics	Y			Y 1		Y 2		Y 4
Update Team	Y	Y	Y 1	Y 1	Y 2	Y 2	Y 4	Y 4
Delete Team	Y	Y	Y 1	Y 1	Y 2	Y 2	Y 4	Y 4
Delete User	Y	Y

What are Collectors?

Collectors can be thought of as an infinitely running background jobs. They constantly run within a set interval then collect data from sources such as GitLab, Jira etc., to transform the data into useable information the backend API can understand.

What collectors do I need?

The number of collectors depends on the tools your team uses for source data, like GitLab or Jira. For each domain (e.g., a Jira board or GitLab instance), you need one collector.

How many collectors do I need?

The number of collectors is determined by the number of domains. For example, two running instances of GitLab might require two instances of the GitLab SCM Collector if you want to track SCM data (commits, branches, merge requests) for both. For details refer to the Collector Environmental Variables section below.

Collector Environmental Variables

Every collector needs the following environmental variables for setup:

• DB_USER: the postgres database user.
• DB_PASS: the postgres database user’s password.
• DB_HOST: the postgres database host.
• DB_PORT: the postgres database port.
• DB_NAME: the postgres database name.
• COLLECTOR_NAME: the name of the collector (the name for a particular running instance of a collector for a particular TARGET_URL). This name needs to be unique for all the collectors that are going to be run.
• COLLECTOR_INTERVAL_SECONDS: the amount of time in seconds the collector needs to sleep before beginning the next round of collection.
• TARGET_URL: the base domain url for where the requests are going to be sent to when collecting. For example, https://example.com.
• LOOK_BACK_DAYS: represents how old of a dataset (measured in days) do we want the collectors to collect data from (for example pull requests that were update 365 days ago for gitlab-scm-collector)
• GO_RUN_ENV: mode of operation for the collector (can be “production” or “development” only).
• COLLECTOR_TARGETS_INTRVL_SECS: represents the amount of time that the top level collection (collector target collection) must wait before collecting again. Ideally 24 hours.
• MAX_REQUESTS_PER_MINUTE: represents the threshold for the amount of requests that can be sent to TARGET_URL in a minute before the collector instance needs to stop sending requests for a brief period of time.
• ACCESS_TOKEN: the token that must be set in order for the collector to retrieve data from whatever API might need the token (example: GitLab, Jira etc.).

Finally, there are additional specifics that some of the collectors will need for which you can find more on the Collector Specifics section.

Environmental Variables needed for the API

The API needs the following environmental variables for the setup: - DB_USER: the postgres database user. - DB_PASS: the postgres database user’s password. - DB_HOST: the postgres database host. - DB_PORT: the postgres database port. - DB_NAME: the postgres database name. - SSO_ENABLED: determines whether the SSO is enabled or not (can only be one of “true” or “false” as value). - SSO_ADMIN_GROUP: the SSO group name for admin access. - SSO_LEADERSHIP_GROUP: the SSO group name for leadership access. - SSO_GROUPS_KEY: the key found in user token indicating the list of groups a user is part of (this can include SSO_ADMIN_GROUP, SSO_LEADERSHIP_GROUP values in the list). This list will determine what SSO permissions a user has. For example, if SSO_GROUPS_KEY="foo" and SSO_ADMIN_GROUP="bar" is set, then the API will try and check the user token (as a sample token json {"foo": ["bar"]}) to determine if user is admin which in this case the user is admin. - SSO_USERNAME_KEY: the key found in user token indicating the user’s username. For example, if the SSO_USERNAME_KEY="foo" is set, then the API would get the username by checking the token (as a sample token json {"foo": "bar"}) for foo as key. In this case, the username would be bar. - RATE_LIMITER_ENABLED: turns on the rate limiter, defaults to true. - RATE_LIMITS: how often an IP address can make requests of the API. Defaults to 300/day,50/hour. The format can be seen here: https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation - RATE_LIMITING_IP_WHITELIST: a comma-delineated list of IP addresses to exempt from rate limiting. - CIRCUIT_BREAKER_ENABLED: turns on the circuit breaker, defaults to true. - OPENAPI_VERSION: the open api version for the app to use. - MODE: the mode of operation for the app (can be “production” or “development”)

Experimental features that can be enabled

The API can enable experimental features by setting the variable name that describes the feature as true. For example, FEATURE_XXX="true". where XXX is the feature name.

TEAM_VIEWS

If this experimental feature is enabled, then alternative views can be made for a team. These alternative views will not get included in the rollup for owning value stream or organization. This allows a team to use a second board that only includes a subset of their workflow (maybe only high priority items), allowing a different set of metrics to be viewable without double counting items for the value stream or organization.

COST_METRICS

If this experimental feature is enabled, then a separate dashboard showing the metrics with currency calculations instead of time. If SSO is enabled as well, then only users that are part of a specific SSO group can access this part of the application. This can be provided to the API with the environment variable SSO_LEADERSHIP_GROUP.

The cost metrics are built using pay data that is uploaded in a CSV format. Once again, if SSO is enabled, only those who are part of the previously mentioned SSO group can upload this data. The CSV should include pay rates and e-mail addresses.

DEPLOY_FREQUENCY

If this experimental feature is enabled, Holocron will report metrics on how often team’s deploy their projects. This is based on build job status and as such requires a consistent use of job names.

API_V3

If this experimental feature is enabled, new routes will be available at /api/v3 with some breaking changes:

• Pagination now exists on all endpoints returning lists. Pagination can be managed with the page and per_page query parameters. per_page has a default and max value of 100.
• /gitrequests is now /git-requests. Similar changes for /project-issues and /ticket-boards.

Collector Specifics

GitLab Workflow Collector:

This collector also utilizes the following environment variables:

• HIGHEST_PRIORITY_LABELS: Comma delineated list identifying a ticket as highest priority.
• HIGH_PRIORITY_LABELS: Comma delineated list identifying a ticket as high priority.
• MEDIUM_PRIORITY_LABELS: Comma delineated list identifying a ticket as medium priority.
• LOW_PRIORITY_LABELS: Comma delineated list identifying a ticket as low priority.
• LOWEST_PRIORITY_LABELS: Comma delineated list identifying a ticket as lowest priority.
• DEFAULT_TICKET_PRIORITY: The priority to use if no matching label is found. Also used in case of conflict between label lists. Possible values are HIGHEST, HIGH, MEDIUM, LOW, LOWEST. Defaults to LOWEST.
• FEATURE_LABELS: Comma delineated list identifying a ticket as a feature ticket.
• DEFECT_LABELS: Comma delineated list identifying a ticket as a defect ticket.
• MAINTENANCE_LABELS: Comma delineated list identifying a ticket as a maintenance ticket.
• UNPLANNED_LABELS: Comma delineated list identifying a ticket as an unplanned ticket.
• DEFAULT_TICKET_TYPE: The type to use if no matching label is found. Also used in case of conflict between label lists. Possible values are FEATURE, DEFECT, MAINTENANCE, and UNPLANNED. Defaults to FEATURE.

In addition to the setup needed for environmental variables, you will need the following requirements to be met in order to be able to use this collector: 1. Your hosted GitLab’s GraphQL maximum query complexity must be no lower than 234. 2. Your hosted GitLab must be Enterprise Edition (currently only tested against v16).