Skip to content

Latest commit

 

History

History
121 lines (90 loc) · 5.92 KB

admin-interface.md

File metadata and controls

121 lines (90 loc) · 5.92 KB
Raw

Administration Interface

As of June 2020 we are migrating some administrational functions to a new technology stack. The back-end uses TypeORM to connect to the Portal's database and provides a GraphQL API using TypeGraphQL. The front end uses ReactAdmin to provide a Material UI interface for administrators.

The goals for this work are described in this document: Portal Admin design.

Admin panel work is in the ./admin-panel/graphql-backend and react-admin-interface directories.

Documentation is split up into three parts:

  1. Quick Start -- Get setup and start working.
  2. Back End — GraphQL server and ORM connectivity
  3. Front End — The administrative UI

Quick Start

At the moment running the admin panel interface is a manual process:

Setup

  1. install certificates into ~/.dignhy/certs
  2. mkcert -cert-file graphql.portal.docker.crt -key-file graphql.portal.docker.key graphql.portal.docker
  3. mkcert -cert-file admin.portal.docker.crt -key-file admin.portal.docker.key admin.portal.docker
  4. Run docker, and start the Portal using ./docker-compose up.
  5. The GraphQL playground should now be running at https://graphql.portal.docker/graphql
  6. You should be able to read the schema at the above playground URL but specific queries will fail unless you authenticate with the portal first. See "Portal Authentication" section below.
  7. you should see the Admin interface running at https://admin.portal.docker/
  8. You should see a button to authenticate with the portal.

Portal Authentication

  1. Ensure that your portal has an oauth client configured for this app.
  2. the client name should be admin-panel, public.
  3. The client should be configured with Redirect URIS matching https://admin.portal.docker/ and https://admin.portal.docker/?PORTAL_URL=https://app.portal.docker
  4. Most of the configuration is done through environment variables, managed by
  5. docker-compose. For the react-admin interface environment variable names must
  6. start with REACT_APP so they get passed down to build process and packaged
  7. for client delivery. To learn more about that, see the create-react-app documentation for custom enviroments

Using the GraphQL Playground with JWT Auth headers:

In local development you can experiment with graphQL queries in the GraphQL playground running at: https://graphql.portal.docker/graphql -- but you need to add HTTP Headers in the bottom left hand panel of the interface. Just add:

{
  "Authorization": "Bearer <TOKEN_VALUE>"
}

where TOKEN_VALUE comes from visiting the portal JWT route when logged in as an administrator or project admin:

https://app.portal.docker/api/v1/jwt/portal

Importing Mysql Entities:

This has already been done, and you shouldn't need to do it again. If the database schema has been substantially modified, you can import the TypeORM entities by running this: MYSQLPASSWORD=xyzzy npm run import. NOTE: You will need review these changes by hand, and re-add TypeGraphQL annotations to any modified entities before checking them back in to git.

Tips and Tools:

  • The react-admin page (front end) is loging data access requests and responses to the console.
  • There is a chrome extension called GraphQL Network that you can use to inspect GraphQL queries that are sent with web requests.
  • There is a JWT Debugger chrome extension you can use to debug JWT Claims

Back End

TypeORM is used to map MySQL records into TypeScript objects. It uses annotations to help describe the object ⟷ relation mapping. You can read the TypeORM Documentation for more info.

TypeGraphQL is used to map help define GraphQL schema types using standard TypeScript definitions. It also uses annotations one these classes and in resolvers to help describe GraphQL Resources in more detail. You can read the TypeGraphQL Documentation for more info.

Apollo server is used as the GraphQL server. You can read the Apollo Server Documentation for more info.

Finally the web server is running an Express server to handle HTTP requests. JWT middleware is added to the Express server to transparenetly handle portal authentication claims.

Front End

The front end uses ReactAdmin. React Admin is an API agnostic front end that provides a complete UI Toolkit for stanrdard CRUD operations.

React admin leaves the details of connecting to an API to a Data Provider. Data Providers are not terribly hard to write, but to connect to our GraphQL backend, we are using a standard pre-made DataProvider called ra-data-graphql-simple

Under the hood, ReactAdmin is using Material UI to provide its widget set and theme support.