Skip to content

Commit 4bb34ed

Browse files
peppescgclaude
peppescg
and
claude
committed
Add Cloud UI documentation section
Closes #870. Adds a new Cloud UI section under Platform capabilities with an introduction, Docker Compose quickstart, and configuration guide covering environment variables, OIDC setup, and deployment options (Docker, Compose, Helm). Adds cross-reference from the Registry Server index page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c288159 commit 4bb34ed

5 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎docs/toolhive/guides-cloud-ui/configuration.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Cloud UI configuration
3+
sidebar_label: Configuration
4+
description:
5+
Configure environment variables, OIDC authentication, and deployment options
6+
for the Cloud UI
7+
---
8+
9+
This guide covers the environment variables and configuration options for
10+
running the Cloud UI in different environments.
11+
12+
## Environment variables
13+
14+
The Cloud UI is configured entirely through environment variables. The table
15+
below lists the required and optional variables.
16+
17+
### Required variables
18+
19+
| Variable | Description |
20+
| -------------------- | --------------------------------------------------------------------------------------- |
21+
| `OIDC_ISSUER_URL` | Issuer URL of your OIDC provider (for example, `https://your-org.okta.com`) |
22+
| `OIDC_CLIENT_ID` | OAuth2 client ID registered with your OIDC provider |
23+
| `OIDC_CLIENT_SECRET` | OAuth2 client secret for the registered client |
24+
| `BETTER_AUTH_SECRET` | Secret used to encrypt session tokens. Generate one with `openssl rand -base64 32` |
25+
| `BETTER_AUTH_URL` | Base URL where the Cloud UI is accessible (for example, `https://cloud-ui.example.com`) |
26+
| `API_BASE_URL` | URL of the Registry Server API (for example, `https://registry.example.com`) |
27+
28+
### Optional variables
29+
30+
| Variable | Description |
31+
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
32+
| `DATABASE_URL` | PostgreSQL connection string for the auth database. When omitted, the Cloud UI uses an in-memory SQLite database |
33+
| `TRUSTED_ORIGINS` | Comma-separated list of allowed CORS origins |
34+
35+
## Configure OIDC authentication
36+
37+
The Cloud UI delegates authentication to an external OIDC provider using
38+
[Better Auth](https://www.better-auth.com/). It works with any
39+
standards-compliant provider, including Okta, Microsoft Entra ID, and Auth0.
40+
41+
To configure your provider:
42+
43+
1. Register a new OAuth2/OIDC application in your identity provider.
44+
2. Set the redirect URI to `<BETTER_AUTH_URL>/api/auth/callback/oidc` (for
45+
example, `https://cloud-ui.example.com/api/auth/callback/oidc`).
46+
3. Copy the issuer URL, client ID, and client secret into the corresponding
47+
environment variables.
48+
49+
:::tip
50+
51+
For local development or testing, use the built-in mock OIDC provider by
52+
starting the Docker Compose stack with the `mock` profile. See the
53+
[quickstart](./quickstart.mdx) for details.
54+
55+
:::
56+
57+
## Deployment options
58+
59+
### Docker
60+
61+
Build and run the Cloud UI as a standalone container:
62+
63+
```bash title="Build the image"
64+
docker build -t toolhive-cloud-ui:latest .
65+
```
66+
67+
```bash title="Run the container"
68+
docker run -p 3000:3000 \
69+
-e OIDC_ISSUER_URL=https://your-org.okta.com \
70+
-e OIDC_CLIENT_ID=your-client-id \
71+
-e OIDC_CLIENT_SECRET=your-client-secret \
72+
-e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
73+
-e BETTER_AUTH_URL=http://localhost:3000 \
74+
-e API_BASE_URL=http://your-registry-server:8080 \
75+
toolhive-cloud-ui:latest
76+
```
77+
78+
The application listens on port 3000.
79+
80+
### Docker Compose
81+
82+
The repository includes a Docker Compose file that starts the full stack (Cloud
83+
UI, Registry Server, and databases). See the [quickstart](./quickstart.mdx) for
84+
a walkthrough.
85+
86+
For production use with a real OIDC provider, create a `.env` file with your
87+
credentials and start without the `mock` profile:
88+
89+
```bash title=".env"
90+
OIDC_ISSUER_URL=https://your-org.okta.com
91+
OIDC_CLIENT_ID=your-client-id
92+
OIDC_CLIENT_SECRET=your-client-secret
93+
BETTER_AUTH_SECRET=your-generated-secret
94+
```
95+
96+
```bash
97+
make compose-up
98+
```
99+
100+
### Kubernetes (Helm)
101+
102+
The Cloud UI repository includes a Helm chart in the `helm/` directory. To
103+
deploy on Kubernetes:
104+
105+
```bash
106+
helm install cloud-ui ./helm \
107+
--set env.OIDC_ISSUER_URL=https://your-org.okta.com \
108+
--set env.OIDC_CLIENT_ID=your-client-id \
109+
--set env.OIDC_CLIENT_SECRET=your-client-secret \
110+
--set env.BETTER_AUTH_SECRET=your-generated-secret \
111+
--set env.BETTER_AUTH_URL=https://cloud-ui.example.com \
112+
--set env.API_BASE_URL=http://registry-server:8080
113+
```
114+
115+
:::info
116+
117+
For production Kubernetes deployments, store sensitive values like
118+
`OIDC_CLIENT_SECRET` and `BETTER_AUTH_SECRET` in a Kubernetes Secret rather than
119+
passing them as Helm values.
120+
121+
:::
122+
123+
The Helm chart supports:
124+
125+
- Replica count and horizontal pod autoscaling (HPA)
126+
- Resource requests and limits
127+
- Liveness and readiness probes
128+
- Ingress configuration
129+
- Custom service types (ClusterIP, NodePort, LoadBalancer)
130+
131+
Refer to the chart's `values.yaml` for the full set of configurable parameters.
132+
133+
## Next steps
134+
135+
- [Publish servers](../guides-registry/publish-servers.mdx) to populate your
136+
catalog with MCP server entries.
137+
- Set up [Registry Server authentication](../guides-registry/authentication.mdx)
138+
to control access to the catalog API.
139+
- Learn about the [Registry Server architecture](../guides-registry/intro.mdx)
140+
to understand how the backend works.

‎docs/toolhive/guides-cloud-ui/index.mdx‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: ToolHive Cloud UI
3+
description:
4+
Browse and manage MCP servers from a web-based catalog backed by the Registry
5+
Server
6+
---
7+
8+
import DocCardList from '@theme/DocCardList';
9+
10+
## Introduction
11+
12+
The ToolHive Cloud UI is a web application that gives your team a shared catalog
13+
of MCP servers. It connects to a [Registry Server](../guides-registry/index.mdx)
14+
and displays every registered server in a browsable interface, so team members
15+
can discover available servers and copy connection URLs into their AI agents or
16+
clients.
17+
18+
Use the Cloud UI when you want to:
19+
20+
- Give your team a single place to discover MCP servers without using the CLI or
21+
desktop app.
22+
- Provide a self-service catalog where users copy server URLs directly into
23+
their AI workflows.
24+
- Layer authentication on top of the catalog with your existing identity
25+
provider (IdP).
26+
27+
:::note
28+
29+
The Cloud UI is a **read-oriented catalog** that works alongside the Registry
30+
Server. It does not start or stop MCP servers. To manage server lifecycles, use
31+
the [ToolHive CLI](../guides-cli/index.mdx),
32+
[ToolHive UI](../guides-ui/index.mdx), or
33+
[Kubernetes Operator](../guides-k8s/index.mdx).
34+
35+
:::
36+
37+
## Architecture overview
38+
39+
The Cloud UI is a Next.js application with two main dependencies:
40+
41+
- **Registry Server** - provides the MCP server catalog through the
42+
[MCP Registry API](../reference/registry-api.mdx). The Cloud UI reads server
43+
entries from this API.
44+
- **OIDC provider** - handles user authentication. The Cloud UI uses
45+
[Better Auth](https://www.better-auth.com/) with any standards-compliant OIDC
46+
provider (Okta, Microsoft Entra ID, Auth0, and others).
47+
48+
```text
49+
+-----------+ +----------+ +-----------------+
50+
| Browser | ----> | Cloud UI | ----> | Registry Server |
51+
+-----------+ +----------+ +-----------------+
52+
|
53+
v
54+
+---------------+
55+
| OIDC Provider |
56+
+---------------+
57+
```
58+
59+
## Where to start
60+
61+
- **New to the Cloud UI?** Follow the [quickstart](./quickstart.mdx) to deploy a
62+
local instance with Docker Compose.
63+
- **Configuring a deployment?** See [Configuration](./configuration.mdx) for
64+
environment variables, OIDC setup, and deployment options.
65+
- **Setting up the backend?** The Cloud UI requires a running Registry Server.
66+
See the [Registry Server quickstart](../guides-registry/quickstart.mdx) to get
67+
one running.
68+
69+
## Contents
70+
71+
<DocCardList />

‎docs/toolhive/guides-cloud-ui/quickstart.mdx‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: 'Quickstart: Cloud UI'
3+
sidebar_label: Quickstart
4+
description:
5+
Deploy the ToolHive Cloud UI locally with Docker Compose and browse your MCP
6+
server catalog
7+
schema_type: tutorial
8+
---
9+
10+
In this tutorial, you'll deploy the ToolHive Cloud UI alongside the Registry
11+
Server using Docker Compose. By the end, you'll have a running web catalog where
12+
you can browse MCP servers and copy their connection URLs.
13+
14+
## What you'll learn
15+
16+
- How to clone and configure the Cloud UI repository
17+
- How to start the full stack (Cloud UI, Registry Server, and databases) with
18+
Docker Compose
19+
- How to sign in with a mock OIDC provider for local testing
20+
- How to browse the MCP server catalog
21+
22+
## Prerequisites
23+
24+
Before starting, make sure you have:
25+
26+
- [Docker](https://docs.docker.com/get-docker/) and
27+
[Docker Compose](https://docs.docker.com/compose/install/) (v2.20+)
28+
- [Git](https://git-scm.com/downloads)
29+
30+
## Step 1: Clone the repositories
31+
32+
The Cloud UI depends on the Registry Server, which is included as a Docker
33+
Compose reference from a sibling directory. Clone both repositories into the
34+
same parent folder:
35+
36+
```bash
37+
git clone https://github.com/stacklok/toolhive-registry-server.git
38+
git clone https://github.com/stacklok/toolhive-cloud-ui.git
39+
```
40+
41+
Your directory layout should look like this:
42+
43+
```text
44+
parent-folder/
45+
toolhive-registry-server/
46+
toolhive-cloud-ui/
47+
```
48+
49+
## Step 2: Start the stack with mock authentication
50+
51+
Change into the Cloud UI directory and start all services using the `mock`
52+
profile. This profile includes a built-in OIDC mock server so you don't need to
53+
configure a real identity provider:
54+
55+
```bash
56+
cd toolhive-cloud-ui
57+
make compose-up-mock
58+
```
59+
60+
Alternatively, use Docker Compose directly:
61+
62+
```bash
63+
docker compose --profile mock up --build
64+
```
65+
66+
This starts five services:
67+
68+
| Service | Port | Description |
69+
| ---------------- | ---- | -------------------------------------- |
70+
| **cloud-ui** | 3000 | The Cloud UI web application |
71+
| **registry-api** | 8080 | The Registry Server API |
72+
| **auth-db** | 5433 | PostgreSQL database for authentication |
73+
| **postgres** | 5432 | PostgreSQL database for the registry |
74+
| **oidc-mock** | 4000 | Mock OIDC provider for local testing |
75+
76+
Wait until all services are healthy. You can check their status with:
77+
78+
```bash
79+
docker compose --profile mock ps
80+
```
81+
82+
## Step 3: Open the Cloud UI
83+
84+
Open your browser and navigate to `http://localhost:3000`. You'll see the
85+
sign-in page.
86+
87+
Sign in using the mock OIDC provider. The mock provider accepts any credentials,
88+
so you can use any email and password combination.
89+
90+
## Step 4: Browse the catalog
91+
92+
After signing in, you'll see the MCP server catalog. The catalog displays
93+
servers registered in the Registry Server. From here, you can:
94+
95+
- Browse available MCP servers
96+
- View server details and connection information
97+
- Copy server URLs for use in your AI agents or MCP clients
98+
99+
:::tip
100+
101+
The Registry Server starts with a default configuration file. To add your own
102+
MCP server entries, see the
103+
[Registry Server configuration](../guides-registry/configuration.mdx) guide.
104+
105+
:::
106+
107+
## Clean up
108+
109+
To stop all services and remove the containers:
110+
111+
```bash
112+
make compose-down
113+
```
114+
115+
Or with Docker Compose directly:
116+
117+
```bash
118+
docker compose --profile mock down
119+
```
120+
121+
To also remove the database volumes (deletes all stored data):
122+
123+
```bash
124+
docker compose --profile mock down -v
125+
```
126+
127+
## Next steps
128+
129+
- [Configure the Cloud UI](./configuration.mdx) for production use with a real
130+
OIDC provider.
131+
- [Deploy the Registry Server](../guides-registry/deployment.mdx) on Kubernetes
132+
for a production-grade backend.
133+
- Learn about [publishing servers](../guides-registry/publish-servers.mdx) to
134+
populate your catalog.

‎docs/toolhive/guides-registry/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,14 @@ If you want to host and operate your own catalog, use the Registry Server. If
3131
you only need to browse the default ToolHive catalog from the UI or CLI, you do
3232
not need to deploy it.
3333

34+
:::tip
35+
36+
Want a web-based interface for your Registry Server catalog? The
37+
[Cloud UI](../guides-cloud-ui/index.mdx) connects to the Registry Server and
38+
gives your team a browsable catalog with OIDC-based authentication.
39+
40+
:::
41+
3442
## Where to start
3543

3644
- **New to the Registry Server?** Follow the

‎sidebars.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,21 @@ const sidebars: SidebarsConfig = {
261261
],
262262
},
263263

264+
{
265+
type: 'category',
266+
label: 'Cloud UI',
267+
description:
268+
'How to deploy and use the ToolHive Cloud UI to browse and manage MCP servers',
269+
link: {
270+
type: 'doc',
271+
id: 'toolhive/guides-cloud-ui/index',
272+
},
273+
items: [
274+
'toolhive/guides-cloud-ui/quickstart',
275+
'toolhive/guides-cloud-ui/configuration',
276+
],
277+
},
278+
264279
{
265280
type: 'html',
266281
value: 'Shared guides',

0 commit comments

Comments
 (0)