Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (139 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

188 lines (139 loc) · 5.08 KB

Contributing to Kartverket.dev

You want to contribute to Kartverket.dev? Awesome! Thanks a lot for the support :) Here's how you can get started.
To start a local development environment, follow the instructions below.


Issues and roadmap

We use GitHub issues to track bugs and feature requests. You can find the backlog as well as the current roadmap in the following places:


Node (prerequisite)

This project currently uses Node v22, see source of truth mise.toml.

Setup mise

mise is a tool version manager https://mise.jdx.dev/.

mise is optional, you may use nvm, nodenv or any other preferred tool.

  1. Install mise https://mise.jdx.dev/getting-started.html#installing-mise-cli
  2. Activate for your shell https://mise.jdx.dev/getting-started.html#activate-mise
  3. Install tools within repo: mise install (it reads from mise.toml)

The correct node should now apply locally in this project. Check with:

node -v
>>> v22.14.0

Continue by enabling yarn as package manager. corepack is used for this, it comes with node. It will read the correct version from package.json.

corepack enable
corepack install

GitHub integration

  1. Create a personal access token on GitHub with repo and workflow scopes. Authorize for Kartverket after creation.
  2. Create app-config.local.yaml:
integrations:
  github:
    - host: github.com
      token: your-token

Persistent sqlite

  1. mkdir db
  2. add this snippet to your app-config.local.yaml
backend:
  database:
    client: better-sqlite3
    connection:
      directory: /<absolute>/<path>/<to>/<repo>/db

Add local guest user

To app-config.local.yaml add:

auth:
  providers:
    guest: {}

Getting user data and orgs

Using the anonymized data from Kartverket

catalog:
  rules:
    - allow: [Component, API, Location, Resource, Template, Group, User]
  locations:
    - type: file
      target: ../../test_data/org.yaml

To refresh the data, delete your local sqlites and sync with microsoft provider following the instructions below. Then run the script extract_entities.py in /test_data

Using AZ Cli to get org data

Delete the sqlite files in the db folder before syncing. For this you need to have the az cli and microsoft intune installed. After setting up intune you can log in to az cli using: az login --allow-no-subscriptions --scope https://graph.microsoft.com//.default --use-device-code You might have to ask IT to enroll your device. Now you can use the following configuration in app-config.local.yaml to get user data from microsoft graph. (it might take 5-10 minutes to sync)

catalog:
  providers:
  microsoftGraphOrg:
    default:
      tenantId: 7f74c8a2-43ce-46b2-b0e8-b6306cba73a3
      queryMode: 'advanced'
      user:
        filter: accountEnabled eq true and userType eq 'member'
      group:
        filter: >
          startswith(displayName, 'AAD - TF - TEAM')
      schedule:
        frequency: PT1H
        timeout: PT50M

Testing OAuth locally

We run with azure on kubernetes, but for local testing create your own app registration in Azure Portal or use an existing one.
Set the following API permissions: email, offline_access, openid, profile User.Read.

Also remember to configure the redirect URI to http://localhost:7007/api/auth/github/handler/frame

Configure microsoft auth in app-config.local.yaml:

auth:
  environment: development
  providers:
    microsoft:
      development:
        clientId: x
        clientSecret: x
        tenantId: x

To login you NEED to use the anonymized data from Kartverket in test_data/org.yaml.

Find a user in test_data/org.yaml and replace annotations.graph.microsoft.com/user-id with the object ID (OID) for your Microsoft Account found in Azure Portal.

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  annotations:
    graph.microsoft.com/user-id: YOUR-OID-FOUND-IN-ENTRA-ID
  name: Lynn.Villanueva_kartverket.dev
  namespace: default
  uid: 40cdf86d-90a1-44b8-830a-db920aadac82
spec:
  memberOf: []
  profile:
    displayName: Lynn Villanueva
    email: Lynn.Villanueva@kartverket.dev
    picture: https://i.imgur.com/zcal7OY.jpeg

Start the app

yarn install
yarn dev


Plugins

Linguist - Plugin to show languages in github repositories. NB: currently removed, but could be reintroduced.