From 8f89e1cf39e7a125fd55d2b1f2837c67da4914e0 Mon Sep 17 00:00:00 2001 From: a3957273 <89583054+a3957273@users.noreply.github.com> Date: Thu, 8 Feb 2024 20:13:48 +0000 Subject: [PATCH 1/3] Update administration documentation --- .../{configuration => }/app-configuration.mdx | 4 + .../getting-started/authentication.mdx | 100 ------------------ .../getting-started/helm-deployments.mdx | 63 ----------- .../isolated-network-deployment.mdx | 39 ------- .../docs/administration/helm/basic-usage.mdx | 51 +++++++++ .../administration/helm/configuration.mdx | 41 +++++++ .../helm/isolated-environments.mdx | 42 ++++++++ .../create-a-schema.mdx} | 27 +---- .../schemas/upload-a-schema.mdx | 34 ++++++ frontend/pages/docs/directory.tsx | 20 ++-- .../public/docs/bailo_upload_new_schema.png | Bin 0 -> 309099 bytes 11 files changed, 188 insertions(+), 233 deletions(-) rename frontend/pages/docs/administration/getting-started/{configuration => }/app-configuration.mdx (85%) delete mode 100644 frontend/pages/docs/administration/getting-started/authentication.mdx delete mode 100644 frontend/pages/docs/administration/getting-started/helm-deployments.mdx delete mode 100644 frontend/pages/docs/administration/getting-started/isolated-network-deployment.mdx create mode 100644 frontend/pages/docs/administration/helm/basic-usage.mdx create mode 100644 frontend/pages/docs/administration/helm/configuration.mdx create mode 100644 frontend/pages/docs/administration/helm/isolated-environments.mdx rename frontend/pages/docs/administration/{getting-started/configuration/making-a-schema.mdx => schemas/create-a-schema.mdx} (85%) create mode 100644 frontend/pages/docs/administration/schemas/upload-a-schema.mdx create mode 100644 frontend/public/docs/bailo_upload_new_schema.png diff --git a/frontend/pages/docs/administration/getting-started/configuration/app-configuration.mdx b/frontend/pages/docs/administration/getting-started/app-configuration.mdx similarity index 85% rename from frontend/pages/docs/administration/getting-started/configuration/app-configuration.mdx rename to frontend/pages/docs/administration/getting-started/app-configuration.mdx index 4cc1b7398..639583874 100644 --- a/frontend/pages/docs/administration/getting-started/configuration/app-configuration.mdx +++ b/frontend/pages/docs/administration/getting-started/app-configuration.mdx @@ -4,6 +4,10 @@ import DocsWrapper from 'src/docs/DocsWrapper' ## Configuration Files +> ⚠️ Note: If you use Helm this information does not apply to you. We use Helm to automatically configure the +> application for you. Within helm you can manually alter this configuration in +> `infrastructure/helm/bailo/templates/bailo/bailo.configmap.yaml` + Bailo uses [`node-config`](https://github.com/node-config/node-config#readme) for application configuration. `node-config` organizes hierarchical configurations, allowing the user to set a series of overides over a base configuration. diff --git a/frontend/pages/docs/administration/getting-started/authentication.mdx b/frontend/pages/docs/administration/getting-started/authentication.mdx deleted file mode 100644 index d816c35b5..000000000 --- a/frontend/pages/docs/administration/getting-started/authentication.mdx +++ /dev/null @@ -1,100 +0,0 @@ -import DocsWrapper from 'src/docs/DocsWrapper' - -# Authentication - -Bailo is intended to be run in multiple different environments, each of which will have their own standard -authentication and authorisation methods. To enable this, Bailo exposes a class of methods that can be overridden to -integrate with various services. - -By default, we expect the Bailo instance to be run behind a reverse proxy, which sets the following headers to identify -users and their roles: - -- `x-userid` is a unique identifier for a user. -- `x-email` is an optional email address (to send notifications). -- `x-user` is a JSON encoded object containing any other user data. - -Within Nginx, these can be set via the `proxy_set_header` declaration: - -```bash -proxy_set_header X-UserId "user"; -proxy_set_header X-Email "user@example.com"; -proxy_set_header X-User '{"some":"data"}'; -``` - -To support other authentication mechanisms, an administrator can override the `getUserFromReq` method to get this -information from any other method. To do this edit `backend/src/connectors/Authorisation.ts` to override the required -methods from `backend/src/utils/AuthorisationBase.ts`. E.g. - -```javascript -// backend/src/connectors/Authorisation.ts -import AuthorisationBase from '../utils/AuthorisationBase.js' -import { Request } from 'express' - -class Authorisation extends AuthorisationBase { - async getUserFromReq(_req: Request) { - const username = req.get('x-username') - - return { - userId: username, - email: await getUserEmail(username), - data: await getUserData(username), - } - } -} - -export default Authorisation -``` - -In the above example, instead of getting this data from headers passed into the application, we now get the username -from headers and get the users email and data from another method. - -This is called on each request and not cached, so you may want to implement this yourself if you are using expensive -cryptographic functions or making external network requests. - -# Authorisation - -By default Bailo protects models from deployment by requiring an approval by the model owner. Also, only the model owner -is capable of editting a model that has been uploaded. All users can view all models uploaded to the system. - -This is unlikely to be suitable for large organisations, who may wish to integrate their own internal authorisation -system into Bailo. An administrator can integrate with their internal authorisation system by overriding one of the -`canUserSeeX` functions, visible in `backend/src/utils/AuthorisationBase.ts`. Each functino takes in a user object, as -well as the object to view. The function is then expected to return either `true` or `false` depending on if the user -can view that object. - -This authorisation affects both users directly viewing a model, as well as the models visible in the marketplace. - -An example authorisation implemention: - -```javascript -// backend/src/connectors/Authorisation.ts -import AuthorisationBase from '../utils/AuthorisationBase.js' -import { UserDoc } from '../models/User.js' -import { VersionDoc } from '../models/Version.js' - -class Authorisation extends AuthorisationBase { - async getUserFromReq(_req: Request) { - // we now include roles in the user object - return { - userId: 'user', - data: { roles: ['alpha', 'beta', 'gamma'] }, - } - } - - async canUserSeeVersion(user: UserDoc, model: VersionDoc) { - // we can access the roles from the user document - const userRoles = user.data.roles - // our schema has a 'role' field we need users to have to see it - const versionRole = version.metadata.authorisation.role - - // check if the user has the required role - const canAccess = userRoles.includes(versionRole)) - - return canAccess - } -} - -export default Authorisation -``` - -export default ({ children }) => {children} diff --git a/frontend/pages/docs/administration/getting-started/helm-deployments.mdx b/frontend/pages/docs/administration/getting-started/helm-deployments.mdx deleted file mode 100644 index 3e5a991a3..000000000 --- a/frontend/pages/docs/administration/getting-started/helm-deployments.mdx +++ /dev/null @@ -1,63 +0,0 @@ -import DocsWrapper from 'src/docs/DocsWrapper' - -# Helm Deployments - -> At the moment `helm/bailo` is configured for OpenShift deployment, our default deployment target. Support for -> Kubernetes is on the way. We have heard that external organisations have had success already by disabling 'routes' and -> setting 'ingresses' instead. - -## Requirements - -- [HELM CLI](https://github.com/helm/helm/releases) -- [Kubectl](https://kubernetes.io/docs/tasks/tools/) - -### Optional - -OC is required for deployments to OpenShift - -- [OpenShift CLI](https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz) - -## Deployment - -### Setup - -All commands assume they are run in the `helm/bailo` directory. The user should have already authenticated `kubectl` to -their cluster and changed to the correct context: - -1. `kubectl config set-context --current --namespace=bailo` - -To deploy to `OpenShift`, `oc` must also be configured correctly. - -### Configuration - -Deployment options can be overridden by including a `--values ` to a Helm command, or by -using `--set