Skip to main content

Generic RAG frontend configuration

The Generic RAG frontend is the screen where administrators manage an application's documents. DIAL Admin shows it in the application's Parameters tab. This reference covers how the embedding works and every environment variable, checked against frontend 0.1.0. It is for platform engineers who deploy the frontend next to the backend.

What the frontend does​

Release 0.1.0 has one screen, a table of the application's documents with filters and sorting by metadata.

  • Toolbar. Add uploads a document, with a folder, metadata, and an option to overwrite. Import loads a document bundle. Export channel builds and downloads the channel archive.
  • Row actions. Edit, Download, Export, Reindex, and Delete

The frontend's server calls the channel API through DIAL Core, at DIAL_API_URL, with the signed-in user's access token. With sign-in turned off, those calls carry no credentials.

Embedding in DIAL Admin​

  1. DIAL Admin opens the editor URL. When the application's type sets dial:applicationTypeEditorUrl, DIAL Admin 0.22.5 loads it in an iframe. It adds authProvider, theme, id, and applicationName to the URL. id is the application's ID.
  2. The frontend reads the parameters. It applies the theme and uses id to choose the application. It then sends DIAL Admin the ready messages of the visualizer connector.
  3. The user signs in. The Login button opens a pop-up that signs in with the provider named in authProvider.

For this to work, set these:

  • The editor URL. dial:applicationTypeEditorUrl in the type, or the application's editor URL. See Register the application type.
  • Framing. ALLOWED_FRAME_ANCESTORS with the DIAL Admin origin. Without it, the browser refuses to show the frontend in the iframe.
  • The same identity provider as DIAL Admin. DIAL Admin passes its own provider's ID in authProvider. The frontend needs a provider with that ID, and DIAL Core must accept its tokens.
  • HTTPS. Only with an https NEXTAUTH_URL does the frontend mark its session cookies SameSite=None; Secure, which a cross-site iframe needs.

Environment variables​

All variables are read at runtime, on the frontend's server.

DIAL​

VariableDefaultDescription
DIAL_API_URL—Required. The DIAL Core URL that the frontend's server calls
ALLOWED_FRAME_ANCESTORS'none'The origins allowed to frame the frontend, for its Content-Security-Policy: frame-ancestors header
DIAL_ADMIN_URL—The DIAL Admin origin. The frontend uses it to reach the parent window only when the browser doesn't report the parent's origin.
DIAL_APPLICATION_NAMEGeneric RAGThe name that the frontend also sends its ready messages under. It should match the type's display name.
THEMES_CONFIG_URL—The DIAL Chat Themes service. The frontend reads <THEMES_CONFIG_URL>/config.json to render the theme that DIAL Admin passes. Without it, the frontend keeps its own colors.

Sign-in​

Sign-in is off unless NEXTAUTH_URL is set. To turn it on, set the common variables and one provider's block.

VariableDefaultDescription
NEXTAUTH_URL—The frontend's own URL. Setting it turns sign-in on.
NEXTAUTH_SECRET—Required with sign-in. Signs and encrypts the session.
ADMIN_ROLE_NAMESadminComma-separated role names that mark a user as an administrator in the session. Release 0.1.0 doesn't check the mark.
DIAL_ROLES_FIELDdial_rolesThe dot-separated path of the roles claim in the access token
SHOW_TOKEN_SUBfalsetrue logs the token's sub claim in the clear instead of masking it.

A provider is registered only when all its required variables are set. <NAME> variables set the provider's label, SSO by default. <SCOPE> variables set the requested scopes.

Provider, as its IDRequired variablesOptional variables, with defaults
keycloakAUTH_KEYCLOAK_CLIENT_ID, AUTH_KEYCLOAK_SECRET, AUTH_KEYCLOAK_HOSTAUTH_KEYCLOAK_REALM: the issuer becomes <HOST>/realms/<REALM>. AUTH_KEYCLOAK_NAME. AUTH_KEYCLOAK_SCOPE: openid email profile offline_access.
azure-adAUTH_AZURE_AD_CLIENT_ID, AUTH_AZURE_AD_SECRET, AUTH_AZURE_AD_TENANT_IDAUTH_AZURE_AD_NAME. AUTH_AZURE_AD_SCOPE: openid profile user.Read email offline_access.
googleAUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_SECRETAUTH_GOOGLE_NAME. AUTH_GOOGLE_SCOPE: openid email profile offline_access.
auth0AUTH_AUTH0_CLIENT_ID, AUTH_AUTH0_SECRET, AUTH_AUTH0_HOST (the issuer URL)AUTH_AUTH0_NAME. AUTH_AUTH0_AUDIENCE. AUTH_AUTH0_SCOPE: openid email profile offline_access.
cognitoAUTH_COGNITO_CLIENT_ID, AUTH_COGNITO_SECRET, AUTH_COGNITO_HOST (the issuer URL)AUTH_COGNITO_NAME. AUTH_COGNITO_SCOPE: openid email profile.
oktaAUTH_OKTA_CLIENT_ID, AUTH_OKTA_CLIENT_SECRET, AUTH_OKTA_ISSUERAUTH_OKTA_SCOPE: openid email profile. Okta takes no name variable.

The frontend refreshes the access token 5 minutes before it expires.

Set by the image​

VariableValuePurpose
PORT3000The port the server listens on
NODE_ENVproductionRuns the production build

Further reading​