> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Tyk AI Studio on Docker

> Installation guide for the Tyk AI Studio on Docker

## Availability

| Edition | Deployment Type |
| :- | :- |
| [Community](https://tyk.io/docs/ai-management/ai-studio/overview.md#community-edition) & [Enterprise](https://tyk.io/docs/ai-management/ai-studio/overview.md#enterprise-edition) | Self-Managed |

> [!NOTE]
>
> This guide focuses on the Enterprise Edition of Tyk AI Studio. For the Community Edition, please refer to the [Tyk AI Studio GitHub repository](https://github.com/TykTechnologies/ai-studio/blob/main/docs/site/docs/deployment-docker.md).
>
> The Community Edition uses different Docker images (`tykio/tyk-ai-studio` and `tykio/tyk-microgateway`) and does not require a license key.

This guide covers deploying Tyk AI Studio with a Edge Gateway using Docker Compose. In this architecture, AI Studio acts as the **control plane** (hub) and the Edge Gateway acts as the **data plane** (spoke), receiving configuration via gRPC.

> [!NOTE]
>
> The Edge Gateway's image, binary, and directory names use the older name `microgateway` or the abbreviation `mgw` (for example the `tykio/tyk-microgateway-ent` image and the `mgw-data`/`mgw-plugins` directories below). This guide uses "Edge Gateway" in prose for the same component.

## Prerequisites

* [Docker Engine](https://docs.docker.com/engine/install/) 20.10+ and Docker Compose v2
* At least 4 GB RAM available
* A Tyk AI License key (contact [support@tyk.io](mailto:support@tyk.io) or your account manager to obtain)

> [!NOTE]
>
> Running on Podman, containerd, or another container runtime? See [Container Runtimes](https://tyk.io/docs/deployment-and-operations/container-runtimes.md).

## Generate Secrets

Before starting, generate the required secret keys. These will be used in the configuration files to secure communication and encrypt data:

```bash expandable theme={null}
# Secret key for encryption (used for secrets management and SSO)
openssl rand -hex 16
# Example output: a35b3f7b0fb4dd3a048ba4fc6e9fe0a8

# Encryption key for Edge Gateway communication (must be exactly 32 hex chars)
openssl rand -hex 16
# Example output: 822d3d1e0e2d849263e45fc7bb842364

# gRPC auth token (for hub-spoke communication)
openssl rand -hex 16
# Example output: 9f2c4a6b8d0e1f3a5c7d9e1b3a5c7d9e
```

Save these values — you will need them for both the AI Studio and Edge Gateway configuration files.

## Instructions

### 1. Create Directory Structure

Create a new directory for your project and set up the required folders:

```bash theme={null}
mkdir -p tyk-ai-studio/confs
mkdir -p tyk-ai-studio/studio-data
mkdir -p tyk-ai-studio/mgw-data
mkdir -p tyk-ai-studio/mgw-plugins
cd tyk-ai-studio
```

### 2. Create `compose.yaml`

Create a `compose.yaml` file with the following content. This configuration sets up AI Studio, the Edge Gateway, and a PostgreSQL database.

```yaml Expandable expandable theme={null}
networks:
  tyk-network:

services:
  tyk-ai-studio:
    image: tykio/tyk-ai-studio-ent:v2.2.2
    networks:
      - tyk-network
    volumes:
      - ./confs/studio.env:/opt/tyk-ai-studio/.env
      - ./studio-data:/opt/tyk-ai-studio/data
    env_file:
      - ./confs/studio.env
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"   # Admin UI + REST API
      - "9090:9090"   # Embedded AI Gateway
    restart: always

  microgateway:
    image: tykio/tyk-microgateway-ent:v2.2.2
    networks:
      - tyk-network
    volumes:
      - ./confs/microgateway.env:/opt/tyk-microgateway/.env
      - ./confs/analytics-pulse.yaml:/opt/tyk-microgateway/analytics-pulse.yaml
      - ./mgw-data:/opt/tyk-microgateway/data
      - ./mgw-plugins:/var/lib/microgateway
    env_file:
      - ./confs/microgateway.env
    depends_on:
      tyk-ai-studio:
        condition: service_started
    ports:
      - "9091:8080"   # AI Gateway (external 9091 -> internal 8080)
    restart: always

  postgres:
    image: postgres:16
    networks:
      - tyk-network
    environment:
      POSTGRES_USER: tyk
      POSTGRES_PASSWORD: your-db-password
      POSTGRES_DB: tyk_ai_studio
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U tyk -d tyk_ai_studio"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: always

volumes:
  pgdata:
```

### 3. Create `confs/studio.env`

Create the AI Studio configuration file. Replace the `CHANGE-ME` values with the secrets you generated earlier, and add your Tyk AI License key.

```env Expandable expandable theme={null}
# =============================================================================
# Core Settings
# =============================================================================
DEVMODE=true  # Set to false when using HTTPS; required for login over plain HTTP
ALLOW_REGISTRATIONS=true
SITE_URL=http://localhost:8080
FROM_EMAIL=noreply@example.com

# =============================================================================
# Database
# =============================================================================
DATABASE_TYPE=postgres
DATABASE_URL=postgresql://tyk:your-db-password@postgres:5432/tyk_ai_studio?sslmode=disable

# =============================================================================
# Security — CHANGE THESE (use values from "Generate Secrets" above)
# =============================================================================
TYK_AI_SECRET_KEY=CHANGE-ME-generate-with-openssl-rand-hex-16
MICROGATEWAY_ENCRYPTION_KEY=CHANGE-ME-generate-with-openssl-rand-hex-16

# =============================================================================
# Hub-Spoke: Control Plane Mode
# =============================================================================
GATEWAY_MODE=control
GRPC_PORT=50051
GRPC_HOST=0.0.0.0
GRPC_TLS_INSECURE=true
GRPC_AUTH_TOKEN=CHANGE-ME-generate-with-openssl-rand-hex-16

# =============================================================================
# Proxy — Point to external Edge Gateway URL
# =============================================================================
PROXY_URL=http://localhost:9091
TOOL_DISPLAY_URL=http://localhost:9091
DATASOURCE_DISPLAY_URL=http://localhost:9091

# =============================================================================
# Logging
# =============================================================================
LOG_LEVEL=info

# =============================================================================
# Enterprise Edition — REQUIRED for EE images, must be set before first start
# =============================================================================
TYK_AI_LICENSE=your-license-key

# =============================================================================
# Plugin Marketplace (Optional — enables browsing and installing plugins)
# =============================================================================
# AI_STUDIO_OCI_CACHE_DIR must be set to enable the marketplace.
# Without it, the Marketplace page will be empty.
AI_STUDIO_OCI_CACHE_DIR=./data/cache/plugins
AI_STUDIO_OCI_REQUIRE_SIGNATURE=false  # cosign not available in distroless images

# =============================================================================
# SMTP (Optional — required for email invites/notifications)
# =============================================================================
# SMTP_SERVER=smtp.example.com
# SMTP_PORT=587
# SMTP_USER=apikey
# SMTP_PASS=your-smtp-password
```

### 4. Create `confs/microgateway.env`

Create the Edge Gateway configuration file. Ensure the security tokens match the ones used in `studio.env`.

```env Expandable expandable theme={null}
# =============================================================================
# Server Configuration
# =============================================================================
PORT=8080
HOST=0.0.0.0
READ_TIMEOUT=300s
WRITE_TIMEOUT=300s
SHUTDOWN_TIMEOUT=30s

# =============================================================================
# Database (SQLite — default for edge deployments)
# =============================================================================
DATABASE_TYPE=sqlite
DATABASE_DSN=file:./data/edge.db?mode=rwc
DB_AUTO_MIGRATE=true

# =============================================================================
# Hub-Spoke: Edge Mode
# =============================================================================
GATEWAY_MODE=edge
CONTROL_ENDPOINT=tyk-ai-studio:50051
EDGE_ID=edge-1
EDGE_NAMESPACE=default
EDGE_HEARTBEAT_INTERVAL=30s
EDGE_ALLOW_INSECURE=true
EDGE_TLS_ENABLED=false

# =============================================================================
# Security — MUST MATCH AI Studio values
# =============================================================================
EDGE_AUTH_TOKEN=CHANGE-ME-must-match-studio-GRPC_AUTH_TOKEN
ENCRYPTION_KEY=CHANGE-ME-must-match-studio-MICROGATEWAY_ENCRYPTION_KEY

# =============================================================================
# Gateway
# =============================================================================
GATEWAY_TIMEOUT=300s
GATEWAY_ENABLE_FILTERS=true
GATEWAY_ENABLE_ANALYTICS=true

# =============================================================================
# Analytics
# =============================================================================
ANALYTICS_ENABLED=true
ANALYTICS_BUFFER_SIZE=1000
ANALYTICS_FLUSH_INTERVAL=10s
ANALYTICS_RETENTION_DAYS=90
# Request and response bodies are stored (and sent by the pulse) only when enabled
ANALYTICS_STORE_REQUESTS=false
ANALYTICS_STORE_RESPONSES=false

# =============================================================================
# Analytics Pulse Plugin (sends data to control plane)
# =============================================================================
PLUGINS_CONFIG_PATH=/opt/tyk-microgateway/analytics-pulse.yaml

# =============================================================================
# Cache
# =============================================================================
CACHE_ENABLED=true
CACHE_TTL=1h

# =============================================================================
# Logging
# =============================================================================
LOG_LEVEL=info

# =============================================================================
# OCI Plugin Support
# =============================================================================
OCI_PLUGINS_CACHE_DIR=/var/lib/microgateway/plugins
OCI_PLUGINS_REQUIRE_SIGNATURE=false  # cosign not available in distroless images

# =============================================================================
# Enterprise Edition — REQUIRED for EE images, must be set before first start
# =============================================================================
TYK_AI_LICENSE=your-license-key
```

### 5. Create `confs/analytics-pulse.yaml`

This configures the Edge Gateway to send analytics data back to the AI Studio control plane:

```yaml Expandable expandable theme={null}
version: "1.0"

data_collection_plugins:
  - name: "analytics_pulse"
    enabled: true
    hook_types: ["analytics", "budget", "proxy_log"]
    replace_database: false
    priority: 100
    config:
      interval_seconds: 10
      max_batch_size: 1000
      max_buffer_size: 10000
      compression_enabled: true
      include_proxy_summaries: true
      include_request_response_data: true  # Needs ANALYTICS_STORE_REQUESTS/RESPONSES=true on the edge
      edge_retention_hours: 24
      excluded_vendors: ["mock", "test"]
      timeout_seconds: 30
      max_retries: 3
      retry_interval_secs: 5
```

### 6. Start Services

> [!NOTE]
>
> **Important:** Make sure all configuration files (`studio.env`, `microgateway.env`, `analytics-pulse.yaml`) exist before running `docker compose up`. If a file-mounted volume target does not exist, Docker will create it as a directory, causing errors.

Start the services using Docker Compose:

```bash theme={null}
docker compose up -d
```

### 7. Verify

Check that all services are running correctly:

```bash expandable theme={null}
# Check all services are running
docker compose ps

# Check AI Studio is responding
curl -s http://localhost:8080/health

# Check Edge Gateway is responding
curl -s http://localhost:9091/health

# Check AI Studio logs for successful edge connection
docker compose logs tyk-ai-studio | grep -i "edge\|grpc"
```

### Accessing AI Studio

Once the services are running, you can access the different components:

* **AI Studio UI**: `http://localhost:8080`
* **Embedded Gateway**: `http://localhost:9090`
* **Edge Gateway**: `http://localhost:9091`

## First User Registration

After you start the services, create the first user:

1. Open `http://localhost:8080` in your browser.
2. Select **Sign up**, then enter a name, an email address, and a password.
3. Log in with the new account.

> [!NOTE]
>
> The first user who registers becomes the administrator. You can use any email address. Other users must verify their email address before they can log in, so configure SMTP before you invite them. AI Studio ignores the deprecated `ADMIN_EMAIL` variable.

## Shared Secrets Reference

These values **must match** between the AI Studio and Edge Gateway configuration files:

| AI Studio Variable | Edge Gateway Variable | Purpose |
| - | - | - |
| `GRPC_AUTH_TOKEN` | `EDGE_AUTH_TOKEN` | Authenticates the gRPC connection |
| `MICROGATEWAY_ENCRYPTION_KEY` | `ENCRYPTION_KEY` | Encrypts synced configuration data |
| `TYK_AI_LICENSE` | `TYK_AI_LICENSE` | Enterprise license |

## Port Reference

| Port | Component | Purpose |
| - | - | - |
| 8080 | AI Studio | Admin UI + REST API |
| 9090 | AI Studio | Embedded AI Gateway |
| 50051 | AI Studio | gRPC control server (internal) |
| 9091 | Edge Gateway | Edge AI Gateway (mapped from internal 8080) |
| 5432 | PostgreSQL | Database |

## Using an External Database

To use an existing PostgreSQL instance instead of the bundled container, remove the `postgres` service and `pgdata` volume from `compose.yaml`, then update `studio.env`:

```env theme={null}
DATABASE_TYPE=postgres
DATABASE_URL=postgresql://user:password@your-db-host:5432/tyk_ai_studio?sslmode=require
```

## Upgrading

To upgrade to a newer version:

```bash theme={null}
docker compose pull
docker compose up -d
```

## Troubleshooting

> [accordion] Services fail to start
>
> Check the logs for specific services:
>
> ```bash theme={null}
> docker compose logs <service-name>
> ```

> [accordion] Edge Gateway restarts on first start
>
> On the first start, the Edge Gateway can start before the AI Studio gRPC server is ready. The Edge Gateway then logs `Failed to connect to control server` and restarts. This is normal. The `restart: always` policy restarts it until the connection succeeds. Check that all services show `Up`:
>
> ```bash theme={null}
> docker compose ps
> ```

> [accordion] Edge Gateway cannot connect to AI Studio
>
> * Verify `CONTROL_ENDPOINT` in `microgateway.env` matches the AI Studio service name and gRPC port (e.g., `tyk-ai-studio:50051`)
> * Verify `EDGE_AUTH_TOKEN` matches `GRPC_AUTH_TOKEN`
> * Verify `ENCRYPTION_KEY` matches `MICROGATEWAY_ENCRYPTION_KEY`
> * Check that `GATEWAY_MODE=control` is set in `studio.env`

> [accordion] Database connection errors
>
> * Ensure the `postgres` container is healthy: `docker compose ps`
> * Verify `DATABASE_URL` credentials match the `POSTGRES_USER` / `POSTGRES_PASSWORD` in `compose.yaml`
> * For external databases, verify network connectivity and SSL mode

> [accordion] Marketplace page is empty
>
> The Plugin Marketplace requires `AI_STUDIO_OCI_CACHE_DIR` to be set. Without it, the marketplace service does not start and no plugins will appear. Add this to your `studio.env`:
>
> ```env theme={null}
> AI_STUDIO_OCI_CACHE_DIR=./data/cache/plugins
> ```
>
> Restart AI Studio after making this change.
>
> The marketplace is enabled by default (`MARKETPLACE_ENABLED=true`), but it will not function without the OCI cache directory configured.

> [accordion] Port conflicts
>
> If ports **8080, 9090, or 9091** are already in use, change the **left-hand side** of the port mapping in `compose.yaml`:
>
> ```yaml theme={null}
> ports:
>   - "8585:8080"   # Map to 8585 instead of 8080
> ```
>
> Then update `SITE_URL` in `studio.env` accordingly.