Ask Release Docker Deployment Guide

This guide covers what you need to deploy Ask Release on-premises with Docker. The deployment model, the prerequisites, how to enable Ask Release in Release, and how to start and verify the services. The Docker Compose files, the full environment-variable reference, network-flow, backup and disaster recovery, and private-CA trust all live in the Ask Release Docker Repository.

info

Ask Release requires Digital.ai Release with the built-in MCP server enabled. The minimum supported Release version is 26.3. For more information, see the Ask Release Docker Repository.

For the complete set of Ask Release features and capabilities, see Ask Release.

Prerequisites

• Digital.ai Release 26.3 or later, installed, licensed, and running on-premises.
• Release is already configured for OIDC. Ask Release reuses your Release OIDC setup and does not add its own login. If you use Digital.ai Identity Service, you can use it as the OIDC provider.
• The built-in MCP server is enabled in Release. See AI Settings.
• Docker Engine and the Docker Compose plugin are installed on the host.
• PostgreSQL 14 or later is provisioned and reachable. The Release Assistant and the LLM Service both need PostgreSQL, you can host both databases on one server (for example, dai_assistant and dai_llm).
• An OIDC issuer with a JWKS endpoint reachable from the Release Assistant and the LLM Service.
• Access to the container registry hosting the Ask Release images.
• For self-hosted LLM mode, an LLM provider endpoint and credentials.

Deployment Model

On-premises, you run two services with Docker:

• Release Assistant: Receives questions from the Ask Release UI, orchestrates the response, and streams it back. Install the latest image from Release Assistant.
• LLM Service: Processes natural language requests and calls your configured model provider (llm-service-api, with a one-time llm-service-dbinit container for database schema initialization). Pull the latest LLM Service images from LLM Service API and LLM Service Database Initialization.

You provide and operate the supporting components yourself:

• Digital.ai Release (your existing instance), which hosts the built-in MCP server the Assistant calls.
• An OIDC identity provider (your own, or the Digital.ai Identity Service).
• PostgreSQL for the Release Assistant and the LLM Service.
• A model provider endpoint (for example, OpenAI, Anthropic, or AWS Bedrock).

There is no separate MCP container. The MCP server is embedded in Release and is exposed at ${RELEASE_PUBLIC_URL}/s/mcp the Assistant connects to it directly with the signed-in user's token. When you run your own identity provider and model provider, the deployment runs fully self-contained, with no runtime calls to Digital.ai-hosted services. This is a single-host Docker deployment and is not highly available.

info

The root Docker Compose files ship the production services. In production, you provide and maintain your own Digital.ai Release, identity provider, and PostgreSQL. The repository includes an optional test-lab package that you can use to try out the installation before your production deployment. See Quickstart. The test-lab setup is for testing and demo purposes only it is not for production use and is not covered by Digital.ai support.

How It Works

1. A user asks a question in the Ask Release UI in Release.
2. The UI sends the question, with the user's token, to the Release Assistant.
3. The Assistant validates the token against your OIDC provider.
4. The Assistant calls Release's built-in MCP server with the user's token to fetch the Release data needed. Release RBAC applies, so results are scoped to what the user can access.
5. The Assistant calls the LLM Service, which invokes your model provider to generate the response.
6. The response streams back to the Ask Release UI.

For the architecture diagram, see Ask Release.

Security and RBAC

Ask Release does not replace Release authorization it delegates to Release APIs. If a user cannot view or modify an object directly in Release, Ask Release cannot expose or mutate it.

• Authenticated access: Uses your existing Release session through your OIDC provider. No separate credentials.
• Permission-scoped: The embedded MCP endpoint calls the Release API with the authenticated user's token, not elevated service credentials, so Release RBAC decides what is returned.
• Read-only: Ask Release retrieves and displays information only. It cannot start releases, approve tasks, or change data.
• Scoped to Release data: Queries run against Digital.ai Release only.
• Audit logged: Operations are recorded for compliance and traceability.

caution

Do not include sensitive information such as passwords, API keys, or secrets in your prompts.

Authentication

Ask Release authenticates users through your OIDC provider. The Assistant validates the user token against OIDC_ISSUER_URI, reads Release data through the embedded MCP server using that token, and the LLM Service validates the token audience.

Your identity provider needs two OIDC client registrations one for Release and one for the Assistant. The Assistant client (registered as OAUTH2_TOKEN_CLIENT_ID) must have Standard token exchange enabled and an Audience mapper that adds the Release client ID to the aud claim, without these the exchanged token is rejected. For the exact client settings, see the Ask Release Docker Repository.

Network Flows and Sizing

At a high level, the required network flows are:

Source	Destination	Port	Protocol	Required for
User browser	Digital.ai Release	5516	HTTPS	Ask Release UI in Release
User browser	Release Assistant	8090	HTTPS	Chat requests
Release Assistant	Digital.ai Release (embedded MCP)	5516 (/s/mcp)	HTTPS	Tool execution via the embedded MCP endpoint
Release Assistant	LLM Service	9000	HTTPS	Prompt and inference orchestration
Release Assistant	PostgreSQL	5432	TCP	Conversation and session metadata
Release Assistant	OIDC provider	443	HTTPS	Token discovery and JWKS validation
LLM Service	PostgreSQL	5432	TCP	Provider and model configuration
LLM Service	OIDC provider	443	HTTPS	Token discovery and JWKS validation
LLM Service	Model provider	443	HTTPS	Model inference

For the detailed network flow requirements and CPU, memory, and storage sizing recommendations, see the Ask Release Docker Repository.

Deploy

Get the Docker Compose files and helper scripts from the Ask Release Docker Repository, then follow these steps.

Step 1: Configure Hostname Resolution

Release, the Assistant, and the identity provider must resolve to the same fully qualified hostnames across the browser and the services, so TLS certificate names and the OIDC issuer stay consistent. In production, create DNS records for these hostnames. For a single-host trial, add them to the host file instead. Editing the host file requires elevated privileges:

• macOS and Linux (/etc/hosts):

  sudo nano /etc/hosts

• Windows (C:\Windows\System32\drivers\etc\hosts), from an elevated PowerShell:

  Start-Process notepad "C:\Windows\System32\drivers\etc\hosts" -Verb RunAs

Use the same FQDNs in RELEASE_PUBLIC_URL, RELEASE_ASSISTANT_PUBLIC_URL, and OIDC_ISSUER_URI.

Step 2: Enable Ask Release in Release

In your xl-release.conf or xl-release-local.conf, set the Release Assistant URL and enable the AI feature:

features {
  ai {
    assistant-url = "https://release-assistant.example.com:8090"
    enabled = true
  }
}

Restart Release after this change. For Kubernetes-installer setups, this is configured automatically.

Step 3: Configure the Environment

Create a .env file in the project root (copy the repository's .env.base template). At minimum set the OIDC issuer (OIDC_ISSUER_URI), the Assistant OAuth client (OAUTH2_TOKEN_CLIENT_ID, OAUTH2_TOKEN_CLIENT_SECRET), the Release URL (RELEASE_PUBLIC_URL), the Release Assistant database connection, and the image references. For local LLM mode, also set the LLM database, model provider, and tenancy values. For the full variable list, defaults, and LLM provider examples, see the Ask Release Docker Repository.

note

Store secrets such as the OAuth client secret, database passwords, and the LLM provider config in a secret manager and inject them at runtime. Do not commit .env.

Step 4: Start the Services

Run the one-shot database initialization first and wait for it to exit, then start the long-running services:

docker compose --project-directory . \
  --profile with-llm-service up llm-service-dbinit
docker compose --project-directory . \
  --profile with-llm-service up -d llm-service-api release-assistant

For a deployment that uses an external LLM endpoint instead of the local LLM Service, start only release-assistant. For the full set of profiles and command variants, see the Ask Release Docker Repository.

Step 5: Verify

Check the health endpoints:

curl http://release-assistant.example.com:8090/actuator/health/liveness
curl http://llm-service.example.com:9000/llm/utility/ping

A healthy Release Assistant returns HTTP 200 with liveness UP. The LLM /llm/utility/ping endpoint returns HTTP 200 with an empty body when healthy, so judge it by the status code. Then run an end-to-end chat test in the Release UI and one RBAC negative test to confirm a user cannot retrieve data they are not authorized to view.

Components You Provide

• PostgreSQL: Point the stack at your own PostgreSQL by setting POSTGRES_HOSTNAME and the Assistant and LLM database credentials in .env. Create separate databases and users for the Assistant and the LLM Service. For the exact init SQL, TLS options, and troubleshooting, see the Ask Release Docker Repository.
• Digital.ai Release: Point the Assistant to Release (26.3 or later) by setting RELEASE_PUBLIC_URL and RELEASE_ASSISTANT_PUBLIC_URL. The Assistant reaches the embedded MCP endpoint with the user's token. Register the Release OIDC client as described in Authentication. For the full procedure, see the Ask Release Docker Repository.

Quickstart

To try Ask Release before a production deployment, use the optional test-lab package in the Ask Release Docker Repository. It stands up the supporting components (Digital.ai Release, Keycloak, PostgreSQL, and optionally NGINX) alongside the Ask Release services on a single host over HTTP, with no TLS or reverse proxy to configure.

Follow the Quick Start Guide for the step-by-step install, verification, and teardown commands. The rest of this section covers the details you will reference while following that guide: the container images to pull, the LLM provider configuration, the sign-in users, common issues, and how to reset the stack between runs.

The test-lab setup is for testing and demo purposes only. It is not for production use and is not covered by Digital.ai support.

Container Images

Pull the Digital.ai images from Docker Hub and use the latest available tag:

Component	Docker Hub repository
Digital.ai Release	xebialabs/xl-release
Release Assistant	xebialabs/dai-release-assistant
LLM Service API	xebialabs/llm-service-api
LLM Service DB init	xebialabs/llm-service-dbinit

If the LLM Service API and DB init images are not yet available on Docker Hub, obtain the image references from Digital.ai Support and set them in your .env file as LLM_SERVICE_API_IMAGE and LLM_SERVICE_DBINIT_IMAGE. Keycloak, PostgreSQL, and NGINX are pulled from their public registries using the tags set in the .env.base template.

LLM Provider Configuration

The LLM Service reads its provider configuration from LLM_SERVICE_DEFAULT_PROVIDER_CONFIG, which must be base64-encoded JSON. Fill in a provider JSON based on the examples in the repository's llm-service folder and base64 encode it, following the steps in the Quick Start Guide.

Sign-In Users

The test-lab Keycloak realm ships with preconfigured users. Each user's password equals the username. For a first login to Digital.ai Release and Ask Release, use one of:

Username	Password
gandalf	gandalf
alice	alice
bob	bob

For the Keycloak admin console, use admin / admin. For the full user list, see the Test Lab Guide.

In this lab setup, all authenticated users currently have global admin permissions in Release. These credentials are for local testing only. Do not use them in shared, staging, or production environments.

Tips and Troubleshooting

• Set AI_LLM_CHAT_MODEL to the bare model name returned by the LLM endpoint, for example claude-sonnet-4-6. The provider-prefixed form anthropic.claude-sonnet-4-6 does not work with the local LLM Service.
• To point the LLM Service at a different provider like OpenAI or AWS Bedrock, set the matching provider JSON in LLM_SERVICE_DEFAULT_PROVIDER_CONFIG.
• The Keycloak container reports an unhealthy status because it runs over HTTP in the lab. This does not affect the setup and can be ignored. Keycloak readiness is exposed on the management port (default 25090), not the public HTTP port.

Tear Down and Re-running

The test-lab stack persists state on the host: the PostgreSQL data volume (ask-release-postgres-data) and files generated under the mounted test-lab/ directories (Release config and license, Keycloak realm data, and logs). The database initialization scripts and the Keycloak realm seed, which create the databases, roles, and sign-in users such as gandalf and bob, run only on the first startup against empty data. If you start the stack a second time without clearing this state, initialization is skipped and startup can fail on the leftover data.

Before you re-run the lab, tear the stack down and remove the persisted state:

docker compose --project-directory . \
  -f docker-compose.yaml \
  -f test-lab/docker-compose.yaml \
  --profile with-postgres --profile with-llm-service --profile with-keycloak --profile with-release \
  down --remove-orphans

# Remove the PostgreSQL data volume
docker volume rm ask-release-postgres-data

# Remove generated files, keeping your .env
git clean -fdx -e .env

TLS Note

If the Release Assistant uses a self-signed certificate, open the Release Assistant health URL in the browser once and accept the certificate warning before using Ask Release in the Release UI.