cloudjumpercat · Oct 16, 2026 · Oct 19, 2026 · Oct 20, 2026
@@ -56,7 +56,8 @@ Every v2 AI Gateway page must have this exact frontmatter shape for these fields
 products:
     - ai-gateway          # Only ai-gateway, no other products
 works_on:
-    - konnect             # Only konnect, no on-prem
+    - konnect             # Entities/Policies are always authored in Konnect
+    - on-prem             # Add this only for pages about consuming that config on self-hosted Gateway via deck ai sync/ai2kong (see configure-on-prem.md)
 tools:
     - kongctl             # Optional field. If it exists, must be only kongctl or only konnect-api
 min_version:
@@ -67,8 +68,8 @@ Prefer `kongctl` over `konnect-api` when both would work — it's what every rea
 
 Flag any deviation:
 - `products` containing anything other than `ai-gateway`
-- `works_on` containing `on-prem` or anything other than `konnect`
-- `tools` containing `deck`, `admin-api`, or a mix of `kongctl` and `konnect-api` on the same page
+- `works_on` containing anything other than `konnect` and `on-prem`. `konnect` alone is correct for pages about authoring entities/Policies (there's no on-prem UI or API for that). `on-prem` should only be added alongside `konnect` for pages about running that same 2.x config on self-hosted Gateway (install guides, `configure-on-prem.md`-style conversion content) — flag `on-prem` with `konnect` missing, since on-prem AIGW 2.x still starts from a Konnect-authored entity file.
+- `tools` containing `deck`, `admin-api`, or a mix of `kongctl` and `konnect-api` on the same page. Exception: on-prem-focused pages (`configure-on-prem.md`, `docker-compose.md`) legitimately use `deck` for the `ai2kong`/`ai sync`/`ai dump` conversion workflow — don't flag `deck` there.
 - Missing or wrong `min_version` (must be `ai-gateway: '2.0'`)
 
 #### `content_type` on AI Policy pages
@@ -136,9 +137,11 @@ This should be replaced with a corresponding AI Policy include (e.g. under `_inc
 
 Example codeblocks in how-to guides should use `{% konnect_api_request %}` rather than raw curl or deck commands where they're making API calls. Flag any `curl` commands or `deck` commands in example steps that should be `{% konnect_api_request %}` blocks.
 
-### Konnect-only deployments
+### On-prem deployments
 
-v2 AI Gateway is Konnect-only. Flag any references to on-premises deployments, self-hosted Kong Gateway, or any instructions that only apply to on-prem.
+v2 AI Gateway entities/Policies are always authored in Konnect, and the majority of content is treated as Konnect-first. However, a select few pages discuss running the same 2.x entity/Policy configuration on self-hosted Gateway via `deck ai sync` or `deck file ai2kong`. These are legitimate on-prem references and should not be flagged.
+
+On-prem deployments pass the 2.x entity/Policy configuration through `deck ai sync` or `deck file ai2kong` to convert it into a 3.x compatible format that can be applied to a self-hosted 2.x AI Gateway.
 
 ### Kong Gateway → AI Gateway
 

@@ -27,9 +27,14 @@ Anything under a `v1/` path — `app/_how-tos/ai-gateway/v1/`,
 behavior, and never assume its config shape (plugin fields, IDs, entity
 names) carries over unchanged to v2. It's migration source material only.
 
-v2 is Konnect-only (no on-prem data planes) and uses **Policies**, not
+v2 is Konnect-first (primarily documents the Konnect experience) and uses **Policies**, not
 **Plugins**, for anything AI-specific (AI Proxy / AI Proxy Advanced / AI A2A
 Proxy / AI MCP Proxy are the only exceptions — those stay plugins in v2 too).
+Self-hosted Gateway can
+also run that same 2.x config but is documented sparingly: install 2.x on-prem (`docker-compose.md`) and
+apply the entity file with `deck ai sync`, which converts 2.x entities to 3.x plugins
+under the hood. See `app/ai-gateway/configure-on-prem.md` for the conversion
+workflow and entity→plugin mapping.
 
 ## 2. Docs repo map
 

@@ -31,11 +31,16 @@ adding a `skills` capability to the AI Gateway `AIGatewayModelAPI`, from
 `Kong/platform-api#3398` and its PRD). Expect to extend it as more PRDs come
 through with shapes this version hasn't seen yet.
 
-## Scope: AI Gateway 2.0 on Konnect only — Policies, not plugins
+## Scope: AI Gateway 2.0 on Konnect first — Policies, not plugins
 
 This skill documents **AI Gateway 2.0 on Konnect**. That product surface uses
 **Policies** (`app/_ai_gateway_policies/<slug>/index.md`), not self-hosted
 Gateway **plugins** (`app/_kong_plugins/<slug>/`).
+Self-hosted AI Gateway 2.x on-prem is possible, but should be documented sparingly.
+This can run the 2.x config via `deck ai sync`/`deck file
+ai2kong` conversion (see `app/ai-gateway/configure-on-prem.md`). That
+conversion path doesn't change where a new Policy gets documented: still
+`app/_ai_gateway_policies/`, never `app/_kong_plugins/`.
 
 Even when the underlying implementation PR is a `kong-ee` plugin (new Lua
 schema, `kong/plugins/<name>/`, a `changelog/unreleased/kong-aigw/*.yml`

@@ -0,0 +1,255 @@
+---
+title: Install {{site.ai_gateway}} 2.x on-prem using Docker Compose
+content_type: how_to
+permalink: /ai-gateway/install/docker/
+description: Use Docker Compose to install {{site.ai_gateway}} 2.x on self-managed {{site.base_gateway}}
+products:
+  - ai-gateway
+
+works_on:
+  - on-prem
+
+min_version:
+  ai-gateway: '2.2'
+
+tldr:
+  q: How do I install {{site.ai_gateway}} 2.x on-prem using Docker Compose?
+  a: "Create the example Docker Compose file and run `docker compose up -d`."
+
+prereqs:
+  skip_product: true
+  inline:
+    - title: Docker Compose
+      content: |
+        This guide requires [Docker](https://docs.docker.com/get-started/get-docker/) installed on your system.
+
+cleanup:
+  inline:
+    - title: Destroy the {{site.ai_gateway}} containers
+      include_content: cleanup/products/docker
+      icon_url: /assets/icons/ai-gateway.svg
+
+related_resources:
+  - text: Configure {{site.ai_gateway}} on-prem
+    url: /ai-gateway/configure-on-prem/
+  - text: Install {{site.base_gateway}} using Docker Compose
+    url: /gateway/install/docker/
+
+automated_tests: false
+---
+
+## Set up the Docker Compose file
+
+Run the following command to create `docker-compose.yml`:
+
+<!-- vale off -->
+```bash
+cat <<EOF > docker-compose.yml
+
+networks:
+  kong:
+    name: kong
+    driver: bridge
+
+# Image used by every Kong service in this file
+x-kong-image: &kong-image
+  image: kong/kong-ai-gateway:{{ site.data.ai_gateway_latest.version }}
+
+# Common environment variables used by Kong services (migrations and gateway)
+x-kong-db-config: &kong-db-config
+  KONG_DATABASE: postgres             # Use Postgres as the backing database
+  KONG_PG_HOST: db                    # Hostname of the Postgres service
+  KONG_PG_DATABASE: kong              # Name of the database to connect to
+  KONG_PG_USER: kong                  # Database username
+  KONG_PG_PASSWORD: kong              # Database password
+  KONG_PASSWORD: password             # Admin GUI password (required for RBAC)
+  KONG_LICENSE_DATA: "\${KONG_LICENSE_DATA}"  # Kong Enterprise license passed via environment variable
+
+x-kong-container-common: &kong-container-common
+  healthcheck:
+    test: [ "CMD", "kong", "health" ]
+    interval: 3s
+    timeout: 3s
+    retries: 10
+    start_period: 3s
+  restart: on-failure
+  tmpfs:
+    - /tmp
+
+services:
+
+  db:
+    image: postgres:13
+    networks:
+      - kong
+    environment:
+      POSTGRES_DB: kong
+      POSTGRES_USER: kong
+      POSTGRES_PASSWORD: kong
+    healthcheck:                      # Ensure the DB is ready before starting dependent services
+      test: [ "CMD", "pg_isready", "-U", "kong" ]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: on-failure
+
+  kong-migrations:
+    <<: *kong-image
+    networks:
+      - kong
+    command: "kong migrations bootstrap"
+    depends_on:
+      db:
+        condition: service_healthy    # Wait until Postgres is up and healthy
+    environment:
+      <<: *kong-db-config
+
+  kong-gateway:
+    <<: [ *kong-container-common, *kong-image ]
+    deploy:
+      replicas: 1
+    mem_limit: 2g
+    cpus: 4
+    networks:
+      - kong
+    user: "\${KONG_USER:-kong}"
+    ports:
+      - 8000:8000   # Proxy HTTP
+      - 8443:8443   # Proxy HTTPS
+      - 8001:8001   # Admin API
+      - 8002:8002   # Kong Manager (Admin GUI)
+      - 8003:8003   # Dev Portal GUI
+      - 8004:8004   # Dev Portal API
+    depends_on:
+      db:
+        condition: service_healthy
+      kong-migrations:
+        condition: service_completed_successfully  # Start only after bootstrap has succeeded
+    environment:
+      <<: *kong-db-config
+      KONG_ANONYMOUS_REPORTS: "off"
+      KONG_PROXY_LISTEN: "0.0.0.0:8000,0.0.0.0:8443 ssl"
+      KONG_ADMIN_LISTEN: "0.0.0.0:8001"
+      KONG_ADMIN_GUI_LISTEN: "0.0.0.0:8002"
+      KONG_PORTAL_GUI_LISTEN: "0.0.0.0:8003"
+      KONG_PORTAL_API_LISTEN: "0.0.0.0:8004"
+      KONG_LOG_LEVEL: "debug"
+      KONG_PLUGINS: "bundled"
+EOF
+```
+<!-- vale on -->
+
+## Start {{site.ai_gateway}}
+
+Set your Enterprise license in the `KONG_LICENSE_DATA` environment variable:
+
+```sh
+export KONG_LICENSE_DATA='YOUR LICENSE DATA'
+```
+
+Then, start the containers:
+```sh
+docker compose up -d
+```
+
+## Validate
+
+You can validate {{site.ai_gateway}} is running using cURL against the Admin API:
+
+{% control_plane_request %}
+url: ''
+method: GET
+status_code: 200
+{% endcontrol_plane_request %}
+
+This will return an `HTTP/1.1 200 OK` response.
+
+## Configure your on-prem {{site.ai_gateway}} 2.x
+
+For {{site.ai_gateway}} 2.x running on-prem, you'll use {{site.ai_gateway}} 2.x decK configuration files and `deck ai sync` to apply them.
+`deck ai sync` converts the {{site.ai_gateway}} 2.x AI entities and policies into compatible {{site.base_gateway}} 3.x configuration with plugins, Services, and Routes.
+
+You can convert any `kongctl` {{site.ai_gateway}} 2.x configuration to decK by removing the fields that only apply to a {{site.konnect_short_name}}-managed control plane:
+
+* Drop each entity's `ref` field.
+* Drop each entity's `ai_gateway: !lookup {id: ...}` field. On-prem, there's only one {{site.ai_gateway}}, so entities don't need to reference one by ID.
+* Rename the top-level entity collections from their `kongctl` names (`ai_gateway_model_providers`, `ai_gateway_models`, and so on) to their decK names (`model_providers`, `models`). See [Configure {{site.ai_gateway}} on-prem](/ai-gateway/configure-on-prem/) for the full set of entity names decK expects.
+* Add `protocols: [http, https]` under `config.route` on each AI Model. The {{site.ai_gateway}} entity schema defaults to both protocols, but that default isn't carried through by `deck ai sync`/`deck file ai2kong`'s conversion, so the generated Route ends up with {{site.base_gateway}}'s own https-only default instead.
+
+See [{{site.ai_gateway}} 2.x concepts](/ai-gateway/ai-gateway-v2-concepts/) for how the entity model maps to the underlying {{site.base_gateway}} primitives.
+
+For example, here's the [AI Model Provider and AI Model from the {{site.ai_gateway}} get started guide](/ai-gateway/get-started/) written as a decK configuration file instead of a `kongctl` one. Set the `DECK_OPENAI_API_KEY` environment variable to your OpenAI API key, then apply the file with `deck ai sync`:
+
+```sh
+export DECK_OPENAI_API_KEY='Bearer YOUR OPENAI API KEY'
+```
+
+{:.info}
+> This example substitutes `$DECK_OPENAI_API_KEY` directly into the YAML using the shell, instead of decK's own `{% raw %}${{ env "..." }}{% endraw %}` templating. That templating is the documented way to avoid hardcoding secrets (see [Managing sensitive data](/deck/gateway/sensitive-data/)), but it doesn't resolve when a {{site.ai_gateway}} 2.x entity file is applied with `deck ai sync`/`deck file ai2kong`: the literal, unresolved string ends up in the generated plugin config instead of the real key.
+
+<!-- vale off -->
+```sh
+cat <<EOF | deck ai sync --yes -
+model_providers:
+  - name: generic-openai
+    display_name: "generic-openai"
+    type: openai
+    config:
+      auth:
+        type: basic
+        headers:
+          - name: Authorization
+            value: $DECK_OPENAI_API_KEY
+
+models:
+  - name: my-gpt-4o
+    display_name: "my-gpt-4o"
+    type: model
+    capabilities:
+      - generate
+    formats:
+      - type: openai
+    policies: []
+    config:
+      route:
+        paths:
+          - /v1
+        protocols:
+          - http
+          - https
+        model:
+          body_param: model
+          values:
+            - my-gpt-4o
+    targets:
+      - name: gpt-4o
+        provider: generic-openai
+        config:
+          type: openai
+EOF
+```
+<!-- vale on -->
+
+{:.info}
+> This example omits `--kong-addr`, since it defaults to `http://localhost:8001`, which is already where this Docker Compose file exposes the Admin API. If your {{site.ai_gateway}} isn't reachable at that address, or needs authentication, see [Configuring on-prem authentication](/deck/gateway/configuration/).
+
+### Validate your configuration
+
+Send a chat request to verify your setup:
+
+```sh
+curl -X POST "http://localhost:8000/v1/chat/completions" \
+     --no-progress-meter --fail-with-body \
+     -H "Accept: application/json" \
+     -H "Content-Type: application/json" \
+     -H "Authorization: $DECK_OPENAI_API_KEY" \
+     --json '{
+       "messages": [
+         {
+           "role": "user",
+           "content": "Say this is a test!"
+         }
+       ],
+       "model": "my-gpt-4o"
+     }'
+```
@@ -12,6 +12,9 @@ sections:
       - title: "Get started with {{site.ai_gateway}}"
         description: Set up your first {{site.ai_gateway}} instance and start proxying requests to LLM providers.
         url: /ai-gateway/get-started/
+      - title: "Install {{site.ai_gateway}} on-prem"
+        description: Install {{site.ai_gateway}} 2.x on self-managed {{site.base_gateway}} using Docker Compose.
+        url: /ai-gateway/install/docker/
       - path: /ai-gateway/architecture/
       - title: "{{site.ai_gateway}} capabilities"
         description: Learn about the core capabilities of {{site.ai_gateway}}.

@@ -68,6 +68,9 @@ rows:
               content: |
                 To set up {{site.ai_gateway}} using the {{site.konnect_short_name}} UI, sign in to your Konnect account at [cloud.konghq.com](https://cloud.konghq.com/),
                 then navigate to **{{site.ai_gateway}}** and click **New {{site.ai_gateway}}**.
+            - title: On-Prem
+              content: |
+                See [Install {{site.ai_gateway}} 2.x on-prem using Docker Compose](/ai-gateway/install/docker/) for full setup instructions.
   - columns:
       - blocks:
         - type: card

@@ -26,17 +26,14 @@ def search_filters(site)
       }
     end
 
-    def product_latest_release(site) # rubocop:disable Metrics/AbcSize
-      products = site.data['products'].map do |p|
-        p[0].gsub('-', '_')
-      end
-
-      products.each do |product|
-        releases = site.data.dig('products', product, 'releases')
+    def product_latest_release(site)
+      site.data['products'].each_key do |slug|
+        releases = site.data.dig('products', slug, 'releases')
         next if releases.nil?
 
-        site.data["#{product}_latest"] = releases.detect { |r| r['latest'] }
-        site.data["#{product}_releases"] = releases
+        key = slug.gsub('-', '_')
+        site.data["#{key}_latest"] = releases.detect { |r| r['latest'] }
+        site.data["#{key}_releases"] = releases
       end
     end
 

@@ -37,6 +37,10 @@ related_resources:
     url: /plugins/ai-a2a-proxy/
 ---
 
+{:.success}
+> **Setting up a new {{site.ai_gateway}} 2.x on-prem?**<br>
+> See [Install {{site.ai_gateway}} 2.x on-prem using Docker Compose](/ai-gateway/install/docker/) to get {{site.ai_gateway}} 2.x installed first, then use this guide to configure it.
+
 The existing {{site.ai_gateway}} documentation follows the {{site.konnect_short_name}} model: AI Models, AI Model Providers, AI MCP Servers, AI Agents, and more, that you configure in {{site.konnect_short_name}}. See [{{site.ai_gateway}} entities](/ai-gateway/entities/) for the full list. Self-hosted {{site.base_gateway}} doesn't have these objects. This page shows you how to configure the same capabilities with AI plugins on [Services](/gateway/entities/service/) and [Routes](/gateway/entities/route/).
 
 There are two ways to bridge that gap: