How to deploy DCB Admin

This document provides instructions on how to deploy DCB Admin. It describes the environment variables used, procedures for different platforms, and how to resolve common issues that may be encountered in the process.

1 Environment variables
2 Deploying DCB Admin via Vercel
3 Deploying DCB Admin via Amazon Web Services

Environment variables

These are the environment variables used by DCB Admin. Please contact dcb@k-int.com for any secrets you do not already have, as these should never be shared in public channels or forums.

Environment variable	Required?	Expected format	Notes

Environment variable	Required?	Expected format	Notes
DCB_API_BASE	Yes	URL	The URL of the DCB Service server. In situations where there is a 'frontend' and a 'backend' DCB Service server URL available, use the 'frontend' value.
KEYCLOAK_ID	Yes	String	This is the `client_id` from Keycloak, and should always have the value of `dcb`.
KEYCLOAK_URL	Yes	URL in the format `your-keycloak-url/realms/dcb-hub`	The URL of the Keycloak server. Used for authentication, and must be the same as the Keycloak URL used by other DCB applications such as DCB Service.
KEYCLOAK_SECRET	Yes	String	The Keycloak client secret. Can be found in the Keycloak administrative console, by visiting 'Clients', selecting 'dcb' and then 'credentials'
NEXTAUTH_SECRET	Yes	String	Secret from NextAuth, see docs for further information or contact dcb@k-int.com for the value currently in use.
NEXTAUTH_URL	Only for non-Vercel deployments	URL	URL of your DCB Admin deployment. You can find this under ‘All apps’ in the Amplify console.
NEXT_PUBLIC_MUI_X_LICENSE_KEY	Yes, for full functionality.	String	The license key that enables MUI X Pro features in DCB Admin. Please contact dcb@k-int.com for the key itself. If you are seeing a watermark on data grids in DCB Admin, this environment variable is not configured correctly. Please refer to the MUI docs for more information.
DCB_SEARCH_BASE	Yes, for shared index functionality.	URL	This is the URL of your DCB Locate deployment, and enables shared index functionality within DCB Admin.
BLOB_READ_WRITE_TOKEN	Yes, for consortium assets upload.	String	This is the token which enables uploads to Vercel Blob from DCB Admin. Currently this is used to upload assets for consortia so they can self-serve when supplying branding and customisation for DCB Admin. Please contact dcb@k-int.com for this value.

Deploying DCB Admin via Vercel

This section outlines how to deploy DCB Admin via Vercel, which at the time of writing is the platform used for the majority of DCB Admin deployments.

Getting started with a new project

There is already an existing DCB Admin project in Vercel, so there shouldn’t be any need to create a new one. However, here are the steps for doing so in case it ever becomes necessary:

Sign into Vercel and import the ‘dcb-admin-ui’ Git repository.
Follow the on-screen guidance, and supply the environment variables from above when prompted.
You should then have a new Vercel project, created from the DCB Admin repo.

Creating a new deployment

New DCB Admin deployments are frequently required for new environments, customers and situations. To create a new deployment, follow these steps.

First, cut a new Git branch for your deployment.
Go to ‘Deployments' under the dcb-admin project in Vercel and select ‘create new deployment’.
Once this has completed, you will need to define any deployment-specific environment variables in ‘Settings’, and specify the deployment branch.
1. Normally, this requires new values for DCB_API_BASE, KEYCLOAK_URL, KEYCLOAK_SECRET, and DCB_SEARCH_BASE, but this will depend on your deployment.
Follow the guidance for whitelisting the deployment URL in Keycloak from below.
Go to your new deployment and select ‘Redeploy’. This makes the deployment use the new environment variables.
1. If you ever change the environment variables for a deployment, you must re-deploy for the changes to take effect.

Common issues

I’ve created a new deployment, but am unable to log in

This usually occurs when the Keycloak environment variables are incorrect or have not been applied to the correct deployment. Check these values and change if necessary. You will then need to re-deploy.

Another potential cause is failing to whitelist the deployment URL in Keycloak. You must follow the process outlined in step 5 of the ‘Setting up environment variables and Keycloak’ section.

If the environment variables are correct, your deployment URL is whitelisted in Keycloak, and re-deploying does not solve the issue, then your Keycloak server may be down, and you should speak with your system administrator.

Nothing is loading when I log in

This usually occurs because there is an issue with the DCB_API_BASE value provided or with the DCB Service instance itself. Firstly, check that your DCB_API_BASE value is correct and has been applied to your new deployment in Vercel (check under ‘Environment variables’ in Settings).

Secondly, check that your DCB Service instance is running. You can do this by navigating to ‘Service status’ in DCB Admin, which will show you DCB Service health information.

Shared index functionality isn’t working

This usually occurs because a DCB_SEARCH_BASE value was either incorrect or not provided. It can also occur if the DCB Locate instance is experiencing downtime or having issues.

If you are seeing this issue, check the health of your DCB Locate instance with an API call to /health. If it is behaving as expected check your environment variables, and re-deploy.

If none of these steps work, please contact your system administrator.

Deploying DCB Admin via Amazon Web Services

This section outlines how to deploy DCB Admin via AWS Amplify.

Getting started

Sign into the AWS management console and open the AWS Amplify console for your organisation. You should see a page with the title ‘All apps’.
For your first time, you will need to create an Amplify application. To do this, select ‘New app’, and then select ‘Host web app’.
On the next page, select GitHub as your repository provider, and click ‘Continue’.
If you are asked to authorize with GitHub, continue, select openlibraryenvironment, and then choose ‘select repositories’ and select dcb-admin-ui from the dropdown.
On the ‘Add repository branch’ page,
1. select the dcb-admin-ui repository (https://github.com/openlibraryenvironment/dcb-admin-ui)
2. select the release branch and continue.
On the ‘build settings’ page, select ‘Enable SSR logs' if it is not automatically selected, and then choose ‘Create and use a new service role’ to allow Amplify to automatically create a service role for you.
1. If you have a previously created service role that you want to use instead, select that option.
Choose ‘Next’, and then click ‘Save and deploy’.

If you notice that the framework for your app is automatically set to ‘web’ instead of ‘Next.js - SSR', please scroll down to the ‘Common errors' section of this document and follow the instructions for updating the framework manually.

This section also has instructions for updating the app platform manually - on rare occasions Amplify will automatically set it to ‘Web’ when it should be ‘Web compute’.

For more information, please refer to the relevant AWS Amplify docs.

Setting up environment variables and Keycloak

To set up the necessary environment variables for DCB Admin, you must navigate to ‘App settings’ and then to ‘Environment variables’.
Add the required environment variables from the table below. Some of these variables are deployment-specific, and others will need to come from your Keycloak configuration.
You will then need to modify the Amplify build specification file amplify.yml to make these variables accessible to Next.js. This can be found under ‘App build specification’ in ‘Build settings’. Simply click ‘Edit’ and add these lines under build: commands:

        - env | grep -e DCB_ >> .env.production
        - env | grep -e KEYCLOAK_ >> .env.production
        - env | grep -e NEXTAUTH_ >> .env.production

Save your changes and redeploy your application - go to ‘All apps', click on your deployment and select ‘redeploy this version’.
Navigate to your Keycloak Admin UI, select dcb-hub and then select dcb from ‘clients'. You will then need to add the URL of your deployment to ‘Valid redirect URIs’ and 'Valid post-logout redirect URIs’ like so: https://<your-app-URL>/*. This must be done for all URLs to which DCB Admin is deployed.

For more information please refer to the official documentation.

Common errors and how to solve them

If you encounter the following error (or similar) when deploying DCB Admin, there is a simple fix: CustomerError: It looks like you are attempting to deploy a Next.js SSR app, but your app's framework looks wrong. Please update your app's framework to 'Next.js - SSR' to ensure that your app is deployed correctly.
- Solution: Run the following command in CloudShell. This will update the framework manually:
  - aws amplify update-branch --app-id <value> --branch-name <value> --framework 'Next.js - SSR'
  - The value of app-id can be found under ‘App ARN’ in App settings → General. It is the value at the end of the ARN (highlighted in the screenshot)
If you deploy successfully, but encounter a 404 Not Found page when you click on the branch URL, your app platform may have been set incorrectly by Amplify (see this GitHub issue - it should be Web compute). To fix this, run the command aws amplify update-app --app-id <APP_ID> --platform WEB_COMPUTE --region <REGION>, getting the value of app-id with the method described above.
If you encounter an error when attempting to login (i.e. the URL changes to indicate an OAuthSignInError), please confirm that your Keycloak server is up, and that you have added the correct URL of your DCB Admin deployment to the ‘Valid redirect URIs’ and ‘Valid post-logout redirect URIs’ in your Keycloak admin UI.
If you encounter an error connecting to the repository, please contact Knowledge Integration.
Amplify docs can be found here for further context and troubleshooting Welcome to AWS Amplify Hosting - AWS Amplify Hosting