Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(ai-gateway): show a deploy placeholder on self-hosted instances without a gateway (#19269)

Tobias Wochingercf25748827d0
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsx
index 0f3f081ea9..b3481da44e 100644
--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx
+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx
@@ -1,4 +1,5 @@
import { renderHook } from "@testing-library/react";
+import { useSession } from "next-auth/react";
import { useHasEntitlement, usePlan } from "@/src/features/entitlements";
import { useIsFeatureEnabled } from "@/src/features/feature-flags";
@@ -106,6 +107,8 @@ vi.mock("@/src/features/feature-flags/hooks/useIsFeatureEnabled", () => ({
default: vi.fn(),
}));
+vi.mock("next-auth/react", () => ({ useSession: vi.fn() }));
+
const getSetupStatusQuery = vi.hoisted(() => vi.fn());
vi.mock("@/src/utils/api", () => ({
api: { aiGateway: { getSetupStatus: { useQuery: getSetupStatusQuery } } },
@@ -114,6 +117,7 @@ vi.mock("@/src/utils/api", () => ({
vi.mock("@/src/features/ai-gateway", () => ({
GatewayApiKeysPage: () => null,
GatewayModelsPage: () => null,
+ GatewayNotDeployedNotice: () => null,
GatewaySetupPage: () => null,
}));
@@ -138,6 +142,11 @@ describe("useOrganizationSettingsPages", () => {
vi.mocked(useIsCloudBillingAvailable).mockReturnValue(false);
vi.mocked(useV4UpgradeUiFlag).mockReturnValue(false);
vi.mocked(useIsFeatureEnabled).mockReturnValue(false);
+ vi.mocked(useSession).mockReturnValue({
+ data: null,
+ status: "unauthenticated",
+ update: vi.fn(),
+ });
getSetupStatusQuery.mockReturnValue({
data: { isConfigured: true },
isPending: false,
diff --git a/web/src/components/design-system/Button/Button.stories.tsx b/web/src/components/design-system/Button/Button.stories.tsx
index f36ada7cd2..0ea438ad29 100644
--- a/web/src/components/design-system/Button/Button.stories.tsx
+++ b/web/src/components/design-system/Button/Button.stories.tsx
@@ -21,16 +21,24 @@ export const VariantMatrix = meta.story({
parameters: { controls: { disable: true } },
render: () => (
<div className="grid grid-cols-2 items-center gap-3">
- {(["primary", "secondary", "destructive", "ghost", "text"] as const).map(
- (variant) =>
- (["default", "sm"] as const).map((size) => (
- <Button
- key={`${variant}-${size}`}
- text={`${variant} / ${size}`}
- variant={variant}
- size={size}
- />
- )),
+ {(
+ [
+ "primary",
+ "secondary",
+ "outline",
+ "destructive",
+ "ghost",
+ "text",
+ ] as const
+ ).map((variant) =>
+ (["default", "sm"] as const).map((size) => (
+ <Button
+ key={`${variant}-${size}`}
+ text={`${variant} / ${size}`}
+ variant={variant}
+ size={size}
+ />
+ )),
)}
</div>
),
diff --git a/web/src/components/design-system/Button/Button.tsx b/web/src/components/design-system/Button/Button.tsx
index 2af095f03b..6b46673864 100644
--- a/web/src/components/design-system/Button/Button.tsx
+++ b/web/src/components/design-system/Button/Button.tsx
@@ -18,6 +18,8 @@ const buttonVariants = cva(
primary: "bg-primary text-primary-foreground hover:bg-primary/90",
secondary:
"bg-secondary text-secondary-foreground hover:bg-secondary/80",
+ outline:
+ "border border-border-contrast bg-background hover:bg-accent hover:text-accent-foreground",
destructive:
"bg-destructive text-destructive-foreground hover:bg-destructive/90",
ghost: "hover:bg-accent hover:text-accent-foreground",
@@ -39,7 +41,13 @@ const buttonVariants = cva(
type ButtonProps = {
text: string;
- variant?: "primary" | "secondary" | "destructive" | "ghost" | "text";
+ variant?:
+ | "primary"
+ | "secondary"
+ | "outline"
+ | "destructive"
+ | "ghost"
+ | "text";
size?: "default" | "sm";
} & (
| {
diff --git a/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.stories.tsx b/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.stories.tsx
new file mode 100644
index 0000000000..c02ccf1132
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.stories.tsx
@@ -0,0 +1,6 @@
+import preview from "@/.storybook/preview";
+import { GatewayNotDeployedNotice } from "./GatewayNotDeployedNotice";
+
+const meta = preview.meta({ component: GatewayNotDeployedNotice });
+
+export const Default = meta.story({});
diff --git a/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.tsx b/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.tsx
new file mode 100644
index 0000000000..1a49471e3e
--- /dev/null
+++ b/web/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice.tsx
@@ -0,0 +1,26 @@
+import { Server } from "@langfuse/icons";
+
+import Header from "@/src/components/layouts/header";
+import { GatewaySetupEmptyState } from "@/src/features/ai-gateway/components/GatewaySetupEmptyState/GatewaySetupEmptyState";
+
+const SELF_HOSTING_DOCS_URL = "https://langfuse.com/self-hosting";
+
+export function GatewayNotDeployedNotice() {
+ return (
+ <div className="flex flex-col gap-4">
+ <Header title="Gateway setup" />
+ <GatewaySetupEmptyState
+ icon={Server}
+ title="The AI Gateway isn't deployed"
+ description="On self-hosted Langfuse, the AI Gateway runs as a separate service. Deploy it next to your Langfuse instance to configure providers, models and gateway keys."
+ actions={[
+ {
+ type: "link",
+ label: "Self-hosting docs",
+ href: SELF_HOSTING_DOCS_URL,
+ },
+ ]}
+ />
+ </div>
+ );
+}
diff --git a/web/src/features/ai-gateway/components/GatewaySetupEmptyState/GatewaySetupEmptyState.tsx b/web/src/features/ai-gateway/components/GatewaySetupEmptyState/GatewaySetupEmptyState.tsx
index 7115982537..600287e3a8 100644
--- a/web/src/features/ai-gateway/components/GatewaySetupEmptyState/GatewaySetupEmptyState.tsx
+++ b/web/src/features/ai-gateway/components/GatewaySetupEmptyState/GatewaySetupEmptyState.tsx
@@ -30,24 +30,38 @@ export function GatewaySetupEmptyState({
</div>
{actions.length > 0 ? (
<div className="flex flex-wrap items-center justify-center gap-2">
- {actions.map((action) =>
- action.type === "menu" ? (
- <MenuAction key={action.label} action={action} />
- ) : (
- <Button
- key={action.label}
- text={action.label}
- icon={action.icon}
- onClick={action.onClick}
- />
- ),
- )}
+ {actions.map((action) => (
+ <EmptyStateAction key={action.label} action={action} />
+ ))}
</div>
) : null}
</div>
);
}
+function EmptyStateAction({
+ action,
+}: {
+ action: GatewaySetupEmptyStateAction;
+}) {
+ switch (action.type) {
+ case "menu":
+ return <MenuAction action={action} />;
+ case "link":
+ return (
+ <Button variant="outline" text={action.label} href={action.href} />
+ );
+ case "button":
+ return (
+ <Button
+ text={action.label}
+ icon={action.icon}
+ onClick={action.onClick}
+ />
+ );
+ }
+}
+
function MenuAction({ action }: { action: MenuActionDefinition }) {
const isDisabled = action.disabled || action.items.length === 0;
return (
@@ -91,4 +105,5 @@ type GatewaySetupEmptyStateAction =
onClick: () => void;
icon?: IconComponent;
}
+ | { type: "link"; label: string; href: string }
| MenuActionDefinition;
diff --git a/web/src/features/ai-gateway/hooks/useGatewaySettingsAccess.ts b/web/src/features/ai-gateway/hooks/useGatewaySettingsAccess.ts
index c5e7eae08e..81ebee86b7 100644
--- a/web/src/features/ai-gateway/hooks/useGatewaySettingsAccess.ts
+++ b/web/src/features/ai-gateway/hooks/useGatewaySettingsAccess.ts
@@ -1,3 +1,5 @@
+import { useSession } from "next-auth/react";
+
import { env } from "@/src/env.mjs";
import { canReadGatewayModels } from "@/src/features/ai-gateway/fns/canReadGatewayModels";
import { useIsFeatureEnabled } from "@/src/features/feature-flags";
@@ -26,6 +28,11 @@ export function useGatewaySettingsAccess(organizationId: string | undefined) {
enableForAdmins: false,
organizationId,
});
+ const session = useSession();
+
+ /** Self-hosted without a gateway: managers get a pointer to the docs. */
+ const showNotDeployedNotice =
+ session.data?.environment.aiGatewayDeployed === false && canManageGateway;
const showManagement = isAiGatewayEnabled && canManageGateway;
/** Members manage their own gateway keys; managers see every key. */
@@ -51,6 +58,7 @@ export function useGatewaySettingsAccess(organizationId: string | undefined) {
return {
canManageGateway,
+ showNotDeployedNotice,
showManagement,
showModels,
showApiKeys,
diff --git a/web/src/features/ai-gateway/index.ts b/web/src/features/ai-gateway/index.ts
index e868056264..6882ad0854 100644
--- a/web/src/features/ai-gateway/index.ts
+++ b/web/src/features/ai-gateway/index.ts
@@ -1,3 +1,4 @@
export { GatewayApiKeysPage } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/GatewayApiKeysPage";
export { GatewayModelsPage } from "@/src/features/ai-gateway/components/GatewayModelsPage/GatewayModelsPage";
+export { GatewayNotDeployedNotice } from "@/src/features/ai-gateway/components/GatewayNotDeployedNotice/GatewayNotDeployedNotice";
export { GatewaySetupPage } from "@/src/features/ai-gateway/components/GatewaySetupPage/GatewaySetupPage";
diff --git a/web/src/features/ai-gateway/server/availability.servertest.ts b/web/src/features/ai-gateway/server/availability.servertest.ts
index 56fe2bfc2c..60685c1d46 100644
--- a/web/src/features/ai-gateway/server/availability.servertest.ts
+++ b/web/src/features/ai-gateway/server/availability.servertest.ts
@@ -2,6 +2,7 @@ import { ForbiddenError } from "@langfuse/shared";
import { describe, expect, it } from "vitest";
import {
+ isGatewayDeployedOnInstance,
isGatewayEnabledForOrganization,
requireGatewayEnabledForOrganization,
} from "./availability";
@@ -69,6 +70,29 @@ describe("self-hosted deployments", () => {
},
);
+ it.each([
+ { environment: { nodeEnv: "production" }, expected: false },
+ {
+ environment: { nodeEnv: "production", deployed: "false" },
+ expected: false,
+ },
+ { environment: deployedSelfHosted, expected: true },
+ {
+ environment: { nodeEnv: "production", cloudRegion: "EU" },
+ expected: true,
+ },
+ { environment: { nodeEnv: "development" }, expected: true },
+ {
+ environment: { nodeEnv: "production", previewPrUrl: PREVIEW_PR_URL },
+ expected: true,
+ },
+ ] as const)(
+ "reports the instance gateway as deployed=$expected for $environment",
+ ({ environment, expected }) => {
+ expect(isGatewayDeployedOnInstance(environment)).toBe(expected);
+ },
+ );
+
it.each([
{ nodeEnv: "development" },
{ nodeEnv: "production", previewPrUrl: PREVIEW_PR_URL },
diff --git a/web/src/features/ai-gateway/server/availability.ts b/web/src/features/ai-gateway/server/availability.ts
index 08e911513e..2206ecf3b0 100644
--- a/web/src/features/ai-gateway/server/availability.ts
+++ b/web/src/features/ai-gateway/server/availability.ts
@@ -32,6 +32,14 @@ const isGatewayDeployed = (environment: GatewayAvailabilityEnvironment) =>
Boolean(environment.cloudRegion) ||
isDevelopmentOrPreview(environment);
+/**
+ * False only on self-hosted instances without LANGFUSE_AI_GATEWAY_DEPLOYED,
+ * which is when the UI points operators to the self-hosting docs.
+ */
+export const isGatewayDeployedOnInstance = (
+ environment = getGatewayAvailabilityEnvironment(),
+): boolean => isGatewayDeployed(environment);
+
/** Unset enables every organization, except on Langfuse Cloud. */
const isEnabledForAllOrganizations = (
environment: GatewayAvailabilityEnvironment,
diff --git a/web/src/features/organizations/OrganizationSettingsPage.tsx b/web/src/features/organizations/OrganizationSettingsPage.tsx
index 883052e3c6..aaadde78dd 100644
--- a/web/src/features/organizations/OrganizationSettingsPage.tsx
+++ b/web/src/features/organizations/OrganizationSettingsPage.tsx
@@ -28,6 +28,7 @@ import { OrganizationFeaturePreviewsSettings } from "@/src/features/feature-flag
import {
GatewayApiKeysPage,
GatewayModelsPage,
+ GatewayNotDeployedNotice,
GatewaySetupPage,
} from "@/src/features/ai-gateway";
import { useGatewaySettingsAccess } from "@/src/features/ai-gateway/hooks/useGatewaySettingsAccess";
@@ -90,6 +91,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {
isLangfuseCloud,
showV4Migration,
showAiGatewayManagement: gatewayAccess.showManagement,
+ showAiGatewayNotDeployedNotice: gatewayAccess.showNotDeployedNotice,
showAiGatewayModels: gatewayAccess.showModels,
showAiGatewayApiKeys: gatewayAccess.showApiKeys,
/** Only managers get disabled entries; others see a notice on the page. */
@@ -113,6 +115,7 @@ const getOrganizationSettingsPages = ({
isLangfuseCloud,
showV4Migration,
showAiGatewayManagement,
+ showAiGatewayNotDeployedNotice,
showAiGatewayModels,
showAiGatewayApiKeys,
gatewaySetupDisabledReason,
@@ -137,6 +140,7 @@ const getOrganizationSettingsPages = ({
isLangfuseCloud: boolean;
showV4Migration: boolean;
showAiGatewayManagement: boolean;
+ showAiGatewayNotDeployedNotice: boolean;
showAiGatewayModels: boolean;
showAiGatewayApiKeys: boolean;
gatewaySetupDisabledReason: string | undefined;
@@ -333,13 +337,15 @@ const getOrganizationSettingsPages = ({
"openai",
"anthropic",
],
- content: (
+ content: showAiGatewayNotDeployedNotice ? (
+ <GatewayNotDeployedNotice />
+ ) : (
<GatewaySetupPage
organizationId={organization.id}
projects={organization.projects}
/>
),
- show: showAiGatewayManagement,
+ show: showAiGatewayManagement || showAiGatewayNotDeployedNotice,
},
{
title: "Models",
diff --git a/web/src/server/auth.ts b/web/src/server/auth.ts
index 01c8366ccd..33e9f2c87c 100644
--- a/web/src/server/auth.ts
+++ b/web/src/server/auth.ts
@@ -18,7 +18,10 @@ import {
parseFlags,
parseFlagsWithOrganizationDefaults,
} from "@/src/features/feature-flags/server";
-import { isGatewayEnabledForOrganization } from "@/src/features/ai-gateway/server/availability";
+import {
+ isGatewayDeployedOnInstance,
+ isGatewayEnabledForOrganization,
+} from "@/src/features/ai-gateway/server/availability";
import { env } from "@/src/env.mjs";
import { createProjectMembershipsOnSignup } from "@/src/features/auth/lib/createProjectMembershipsOnSignup";
import { getSessionLoginAt } from "@/src/features/auth/lib/sessionExpiration";
@@ -894,6 +897,7 @@ export async function getAuthOptions(
env.LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES === "true",
inAppAgentEnabled: isInAppAgentInstanceEnabled(),
aiFeaturesTracingConfigured: isLangfuseAITracingConfigured(),
+ aiGatewayDeployed: isGatewayDeployedOnInstance(),
// Enables features that are only available under an enterprise license when self-hosting Langfuse
// If you edit this line, you risk executing code that is not MIT licensed (self-contained in /ee folders otherwise)
selfHostedInstancePlan: getSelfHostedInstancePlanServerSide(),
diff --git a/web/types/next-auth.d.ts b/web/types/next-auth.d.ts
index 1dd4c06161..86595cac1c 100644
--- a/web/types/next-auth.d.ts
+++ b/web/types/next-auth.d.ts
@@ -72,6 +72,10 @@ declare module "next-auth" {
// opt out of product traces. Optional so existing session mocks need
// not set it.
aiFeaturesTracingConfigured?: boolean;
+ // False only on self-hosted instances without LANGFUSE_AI_GATEWAY_DEPLOYED;
+ // Cloud, development and preview always run a gateway. Optional so
+ // existing session mocks need not set it.
+ aiGatewayDeployed?: boolean;
// Enables features that are only available under an enterprise/commercial license when self-hosting Langfuse
selfHostedInstancePlan: Plan | null;
// V4 migration write mode. Mirrors LANGFUSE_MIGRATION_V4_WRITE_MODE so the