Skip to content

Latest commit

 

History

History
215 lines (152 loc) · 8.37 KB

README.md

File metadata and controls

215 lines (152 loc) · 8.37 KB
Raw

README for db-web-ui

Pre-requisites

  • maven (v3.0+)
  • npm (v18.16.0)

Prepare application properties

  • Copy backend/src/main/resources/config/application.properties to backend/src/main/resources/config/application-local.properties and modify it with your values if necessary.

Build on Local Machine

mvn clean install

Start Full Development Server (Frontend + Backend) on Local Machine

  • first build (see above)

  • map 127.0.0.1 to localhost.ripe.net in your local hosts file

  • cd into the backend sub folder

  • execute (using the Spring Boot Maven Plugin) execute: mvn spring-boot:run -Dspring-boot.run.profiles=local -Dspring.profiles.active=local -Dspring-boot.run.jvmArguments="-Duser.timezone=UTC". On the other hand, you can add a new configuration in Intellij.

  • or Right click on /backend/src/main/java/net/ripe/whois/Application.java run in intellij, make sure to add -Dspring.profiles.active=local

  • access the app at: https://localhost.ripe.net:8443/db-web-ui/

Runtime

Add the -Dspring.profiles.active=<ENV> to the JVM args of the application server.

Valid profile names are local, dev, prepdev, rc and prod.

Properties are read from the /config/application-<ENV>.properties file on the classpath.

To run locally add in the vm options: -Dspring.profiles.active=local -Duser.timezone=UTC

Frontend

Open a terminal and cd into the frontend

Build

  • npm run build-dev
    webpack build Just-in-Time (JIT), used for local development. This build will include source-map - TypeScript code in browser for debugging.

  • npm run build
    webpack build Ahead-of-Time (AOT), which compiles app at build time, used for deployments.

  • npm run start
    Use this along with mvn spring-boot:run. It watches the TypeScript and HTML files for changes and redeploys them when they've changed. In detail: the watch task is triggered by changes in the file system. Access application on https://localhost.ripe.net:4200/db-web-ui/ (port changes after logging, so pay attention to return it to 4200)

Test

  • npm run test
    Running Karma unit tests locally for Angular 6+ with coverage. If you want to run the test one by one using Intellij you need to install a plugin called "karma"

    • Angular Unit test coverage is available locally reports/unittest-coverage/index.html

  • npm run test-remote
    Running Karma unit tests remotely in selenium chrome on 193.0.2.222:4444/wd/hub for Angular 6+ with coverage

  • npm run start-mock
    Starts a server with the same configuration as the E2E tests, except the tests are not run. Use this configuration when you want to see the page as Cypress sees them - useful for fault finding and setting up mocks.
    To be able to run e2e-no-test locally (http://localhost:9002/db-web-ui) with logged in user you will have to check
    hostname -s and then resulted host name (for example laptop-123456.local) add
    127.0.0.1 laptop-123456.local in your host file
    sudo vi /etc/hosts

  • run test using cypress

    • npm run start-mock
    • npm run cypress:open
      This will open cypress, there you could specify the browser and the e2e test that you want to run.

Record Mocks e2e tests

Updating NPM and NPM packages

We use the most recent LTS version for db-web-ui. You can see which version this is by looking on the Node.js download page or by using nvm, a tool for managing local Node installations.

nvm install --lts
nvm use --lts

We use semver ranges so that bugfix versions of packages can be easily updated. To see what will be updated:

npm outdated          # prints a list of non-current packages and their version state
npm update --dry-run  # shows what `npm update` would do
npm update            # bring packages up-to-date

To see which packages were updated, optionally against a branch name, use:

npx diff-package-lock <branchname>

See the diff-package-lock homepage for more information

Linting

  • npm run lint
    Lint rules can be found under frontend/.eslintrc.json

IntelliJ Preferences

  • Editor

    • File Types
      • Ignore Files and Folders
        • node_modules
        • dist
    • Code Style
      • Use single class import (do not allow .* asterisk imports)

  • Project Structure

    • Project Settings
      • Project
        • Project SDK: 11
        • Language level: 11

  • Plugins

    • Install Prettier plugin

  • Languages & Frameworks

    • TypeScript
      • TypeScript language service
      • TSLint
        • Automatic TSLint configuration
    • JavaScript
      • Prettier
        • Prettier package: ~/projects/db-web-ui/frontend/node_modules/prettier
        • Check On 'Reformat Code' action

Architecture

Rules of thumb:

  • All rest calls from angular ui go via java-proxy. Java proxy transparently forwards to backends.
  • In the new angular CRUD-ui (searching, creating, modifying and deleting whois objects) we stick to the "whoisresources-objects-object"-protocol. So when searching for maintainers of sso-user, we return a regular search result. What todo with the star? For the service that delivers info for the upper-right-sso-info, we use a dedicated protocol.
  • When designing new urls for the java-proxy, stick to the whois conventions
  • UI should be as simple as possible: So fetching or pushing information should be done with a single call. The java proxy can aggregate to achieve this.
  • Always try to solve problem in backend. if not possible in java-proxy, as last resort in angular UI. We could promote functions from java-proxy to backend over time, so others can also profit.
  • All services a provided by the java-proxy shall be protected by sso. If not logged in, a 403 shall be returned. The angular UI shall redirect to access.ripe.net on a REST 403

Responsibilities of java-proxy: Non-functional requirements only

  • Security
  • Aggregation
  • Same origin
  • Api-key to backends
  • Caching
  • Flexibilty: fix whois problems temporarily

Things every db-web-ui developer should know

HOWTOs

Ripe web components

Follow user interface guidelines provided by RIPE NCC Technical Design team.

Update angular

Use https://update.angular.io

Matomo

Matomo is our self-hosted web analytics service. We use aggregated statistics to improve the user interface.

User Interface Guidelines

The Technical Design circle has published a storybook of user interface elements that we should use as a style guide: https://storybook.ripe.net

Cookie Compliance Project

If you add or remove a cookie to the application, please notify [email protected].

Do not store personal information in local storage.

Deployment

Generally, we only deploy changes to production from the master branch, from a tag on a specific commit.

The team will review changes on a branch beforehand using a Merge Request, and changes are only merged once all issues are resolved.

Every so often an exception can be made and we deploy from a tag on a branch in these cases:

  • Point releases when we select (cherry-pick) fixes (and nothing else) from master to a branch
  • Hotfix release to fix a critical production issue