feat: support fastify prefix subset (#16)

* feat(fastify): support builtin prefix doc(desktop): README file doc(fastify): README file chore: scripts for creating .env files * feat: subset of Damien's changes Co-authored-by: feugy <[email protected]>
nearform · Dec 14, 2020 · 4c67b31 · 4c67b31
1 parent c62cf58
commit 4c67b31
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,6 @@
 [![ci](https://github.com/nearform/brokeneck/workflows/ci/badge.svg)](https://github.com/nearform/brokeneck/actions?query=workflow%3Aci)
 [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
 
-
 This monorepo contains packages and applications which provide a way to manage users and groups in:
 
 - Auth0
@@ -14,12 +13,16 @@ This monorepo contains packages and applications which provide a way to manage u
 
 ## Getting started
 
+You'll need yarn and lerna installed globally:
+
+- `npm i -g yarn lerna`
+
 The easiest way to try this out is to run the standalone server via `brokeneck-fastify`:
 
 - `lerna bootstrap`
 - `lerna run build`
 - `cd packages/brokeneck-fastify`
-- `cp .env.sample .env`. 
+- `cp .env.sample .env`
 - configure `.env` based on the authentication provider you want to use
 - `yarn start`
 - browse to [`http://localhost:5001`](http://localhost:5001)
@@ -54,11 +57,10 @@ The configured client should be authorized to access the built-in `Auth0 Managem
 
 ### AWS Cognito
 
-When using AWS cognito you must make sure that you have IAM credentials configured for the SDK in the machine running the application, for instance in the `.aws/credentials` file. 
+When using AWS cognito you must make sure that you have IAM credentials configured for the SDK in the machine running the application, for instance in the `.aws/credentials` file.
 
 The configured IAM user must have access to Cognito. The simplest way to do this is to add the `AmazonCognitoPowerUser` _AWS managed policy_ to the user.
 
-
 ### Azure AD
 
 The registered application must have all the necessary `Application permissions` (not `Delegated permissions`) to operate on the relevant objects.
@@ -67,7 +69,7 @@ These basically include all the combinations of the permissions:
 
 - API: `Azure Active Directory Graph` and `Microsoft Graph`
 - Objects: `Directory`, `Users`, `Groups` and `GroupMember`
-- Permissions: `Read.All`, `ReadWrite.All`, `Create`, 
+- Permissions: `Read.All`, `ReadWrite.All`, `Create`,
 
 Not all combinations exists, but you should enabled them when they do.
 

diff --git a/examples/custom-path/index.js b/examples/custom-path/index.js
@@ -13,18 +13,30 @@ async function customPath(fastify, options) {
 
   require('dotenv').config({ path: envPath })
 
-  fastify.register(brokeneck, {
-    ui: {
-      // basename of where the UI is served from
-      basename: '/admin',
-      // url of the GraphQL server used by the UI
-      serverUrl: '/admin/graphql'
-    },
-    mercurius: {
-      // prefix of the GraphQL route in the mercurius configuration
-      prefix: '/admin'
-    }
-  })
+  fastify.register(brokeneck, { prefix: '/admin' })
+
+  fastify.get('/', (req, reply) =>
+    reply.header('Content-Type', 'text/html').send(`<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link
+      rel="stylesheet"
+      href="//fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
+    />
+    <style>
+      body {
+        padding: 1em;
+        font-family: Roboto;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>it's alive!</h1>
+    <p>You'll find the admin UI <a href='admin'>here</a></p>
+  </body>
+</html>`)
+  )
 }
 
 module.exports = customPath
diff --git a/packages/brokeneck-desktop/README.md b/packages/brokeneck-desktop/README.md
@@ -0,0 +1,23 @@
+# brokeneck-desktop
+
+Runs your Admin UI as a desktop application!
+
+## How to use it
+
+1. Make sure you built the UI at least once: run `lerna run build` at root level
+1. Configure brockneck-fastify to serve UI. `packages/brokeneck-fastify/.env` must include `BROKENECK_UI=true`
+1. Start electron: `yarn start`
+
+## How it works
+
+`brokeneck-desktop` is an Electron wrapper which starts your `brokeneck-fastify` server, and opens it as an HTML page.
+It behaves exactly the same as if you were browsing the Admin UI with Chromium browser. The only difference is your server running _within_ the desktop application instead of being hosted and accessed through the wire.
+
+It still requires connectivity to access the actual Authentication provider (Auth0, Azure Active Directory or AWS Cognito).
+
+Anything that UI would store in its local-storage is persisted when you close the application.
+
+## Development
+
+Development should happen on [brokeneck-fastify](../brokeneck-fastify/README.md) & [brokeneck-react](../brokeneck-react/README.md) packages only.
+If you change brokeneck server or UI, rebuild them with the `lerna run build` command at top level, and restart the desktop application with `yarn start`.
diff --git a/packages/brokeneck-fastify/README.md b/packages/brokeneck-fastify/README.md
@@ -0,0 +1,75 @@
+# brokeneck-fastify
+
+Plugs into your favourite Authentication provider (Auth0, Azure Active Directory or AWS Cognito) and exposes GraphQL endpoints for managing it.
+
+It can also serve your Admin UI, or be embedded without your fastify server.
+
+## Auth0 setup
+
+TODO
+
+## Azure Active Directory setup
+
+TODO
+
+### AWS Cognito setup
+
+TODO
+
+## How to use it (standalone mode)
+
+1. Make sure you built the UI at least once: run `lerna run build` at root level
+1. Plug into an Authentication provider (see Configuration section down bellow)
+1. Start: `yarn start`
+
+### Configuration
+
+Configure your server through environment variables.
+For simpler developement, you can use a `.env` file.
+
+- `CORS_ORIGIN` (boolean): enables the [Access-Control-Allow-Origin header](https://www.npmjs.com/package/fastify-cors#options). Set to true to let your UI accessing the server when running in dev mode.
+
+- `BROKENECK_UI` (boolean): enables serving Brokeneck UI.
+
+- `BROKENECK_MERCURIUS_GRAPHIQL` (graphiql|playground): when set, enables serving GraphIQL on http://localhost:5001/graphiqul, or GraphQL playground on http://localhost:5001/playground ([Reference](https://github.com/mercurius-js/mercurius/blob/HEAD/docs/api/options.md#plugin-options)).
+
+- `BROKENECK_PROVIDER` (auth0|azure|cognito): sets the Authentication provider (required).
+
+- `BROKENECK_AUTH0_DOMAIN` (string): the Auth0 domain to connect to. Please follow [the instructions](https://www.npmjs.com/package/auth0#management-api-client) on how to allow your brokeneck server accessing Auth0 Management API.  
+
+- `BROKENECK_AUTH0_CLIENT_ID` (string): the Auth0 client ID this server will use.
+
+- `BROKENECK_AUTH0_CLIENT_SECRET` (string): the Auth0 client secret needed for this server to connect.
+
+- `BROKENECK_AUTH0_CONNECTION` (string): the name of the [Auth0 connection](https://auth0.com/docs/identityproviders) to use when creating new users. `Username-Password-Authentication` is the name of Auth0 default database created for you.
+
+- `BROKENECK_AZURE_TENANT_ID` (string): the Azure Active Directory Tenant Id. Create a [tenant](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) and 
+
+- `BROKENECK_AZURE_CLIENT_ID` (string): the Azure Active Directory client ID this server will use. Register an "App" in your tenant to get your client ID.
+
+- `BROKENECK_AZURE_SECRET` (string): the Azure Active Directory secret needed for this server to connect. Go to your "App" secrets to create one, and use it.
+
+- `BROKENECK_COGNITO_REGION` (string): the AWS region hosting your Cognito User Pool.
+
+- `BROKENECK_COGNITO_USER_POOL_ID` (string): the AWS Cognito User Pool ID to create user into.
+
+
+## How to use it (embedded mode)
+
+`brokeneck-fastify` can be used as a fastify plugin:
+
+
+
+### Configuration
+
+TODO
+
+## How it works
+
+`brokeneck-fastify` TODO
+
+
+## Development
+
+Development should happen on [brokeneck-fastify](../brokeneck-fastify/README.md) & [brokeneck-react](../brokeneck-react/README.md) packages only.
+If you change brokeneck server or UI, rebuild them with the `lerna run build` command at top level, and restart the desktop application with `yarn start`.
diff --git a/packages/brokeneck-fastify/lib/plugin.js b/packages/brokeneck-fastify/lib/plugin.js
@@ -1,7 +1,5 @@
 'use strict'
 
-const fp = require('fastify-plugin')
-
 const envConfig = require('./envConfig')
 const pluginConfig = require('./pluginConfig')
 
@@ -16,4 +14,4 @@ async function plugin(fastify, pluginOptions) {
   await fastify.register(require('./plugins/auth'), options)
 }
 
-module.exports = fp(plugin)
+module.exports = plugin
diff --git a/packages/brokeneck-fastify/lib/plugins/ui/index.js b/packages/brokeneck-fastify/lib/plugins/ui/index.js
@@ -3,7 +3,6 @@
 const path = require('path')
 const util = require('util')
 
-const fp = require('fastify-plugin')
 const pkgDir = require('pkg-dir')
 
 const pluginConfig = require('../../pluginConfig')
@@ -26,7 +25,12 @@ async function ui(fastify, options) {
     engine: {
       ejs: require('ejs')
     },
-    defaultContext: { config: uiOptions },
+    defaultContext: {
+      config: {
+        basename: fastify.prefix || uiOptions.basename,
+        serverUrl: `${fastify.prefix}${uiOptions.serverUrl}`
+      }
+    },
     root
   })
 
@@ -37,8 +41,7 @@ async function ui(fastify, options) {
     prefix: uiOptions.basename
   })
 
-  // todo: how to do this only for the basename instead of the whole app?
   fastify.setNotFoundHandler((_, reply) => reply.view('index.ejs'))
 }
 
-module.exports = fp(ui)
+module.exports = ui