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

# Deploying with Helm

> Install Proxy Hopper on Kubernetes using the official Helm chart.

## Prerequisites

* Kubernetes 1.25+
* Helm 3.8+

## Install

```bash theme={}
helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace
```

This deploys a single-instance Proxy Hopper with the in-memory backend using the default config.

## Supplying your config

### Inline config (simplest)

Pass your `config.yaml` content as a Helm value:

```bash theme={}
helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace \
  --set-file config.inline=config.yaml
```

Or in a `values.yaml` file:

```yaml theme={}
config:
  inline: |
    proxyProviders:
      - name: my-provider
        auth:
          type: basic
          username: user
          password: secret
        ipList:
          - "10.0.0.1:3128"
          - "10.0.0.2:3128"
        regionTag: US-East

    targets:
      - name: general
        regex: '.*'
        ipPool: my-pool
        minRequestInterval: 1s
        numRetries: 3
```

```bash theme={}
helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace \
  -f values.yaml
```

### Existing ConfigMap or Secret

If you manage config separately (via an operator, external-secrets, or sealed-secrets), reference it:

```yaml theme={}
# Reference a ConfigMap — key must be "config.yaml"
config:
  existingConfigMap: my-proxy-hopper-config

# Or reference a Secret (recommended when auth is enabled)
config:
  existingSecret: my-proxy-hopper-secret
```

<Warning>
  When `auth` is enabled in your config (API keys, JWT, OIDC), use `existingSecret` rather than `config.inline` in a values file. Credentials in plain values files can end up in version control or Helm release history.

  Create the secret with:

  ```bash theme={}
  kubectl create secret generic proxy-hopper-config \
    --namespace proxy-hopper \
    --from-file=config.yaml=./config-with-auth.yaml
  ```
</Warning>

## Redis backend

Enable the bundled Redis subchart for pool state persistence and multi-instance HA:

```yaml theme={}
backend:
  type: redis

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false
  master:
    persistence:
      size: 1Gi
```

The chart automatically selects the `-redis` Docker image and wires the Redis URL when `backend.type: redis` is set.

To use an external Redis instance instead of the bundled subchart:

```yaml theme={}
backend:
  type: redis
  redis:
    url: redis://my-external-redis:6379/0

redis:
  enabled: false
```

## Token Server

If you're using [managed auth](/concepts/managed-auth), the chart can deploy your token server image alongside Proxy Hopper — a Deployment plus a ClusterIP Service, with a predictable in-cluster URL derived automatically:

```yaml theme={}
tokenServer:
  enabled: true
  image:
    repository: ghcr.io/your-org/my-token-server   # your image — see /developers/token-server
    tag: latest
  port: 9000    # must match the port your token server listens on
```

Wire it into Proxy Hopper's own config by referencing the chart's URL helper — this keeps the URL correct regardless of the Helm release name:

```yaml theme={}
config:
  inline: |
    server:
      authServer:
        url: '{{ include "proxy-hopper.tokenServerUrl" . }}'
        timeoutSeconds: 10
        refreshThresholdSeconds: 60
        retryIntervalSeconds: 30
        maxRetries: 5
        exposeProxyUrl: false

    targets:
      - name: my-target
        regex: '.*'
        authManaged: true
        ipPool: my-pool
```

If you're using `config.existingConfigMap` / `config.existingSecret` instead of `config.inline`, the template helper isn't available — hard-code the in-cluster URL instead:

```
http://<release-name>-proxy-hopper-token-server:<tokenServer.port>
```

Your token server image only needs to implement `POST /token` and `GET /health` — see [Building a Token Server](/developers/token-server) for the contract and a Python library that implements it for you.

## Ingress

```yaml theme={}
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: proxy-hopper.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: proxy-hopper-tls
      hosts:
        - proxy-hopper.example.com
```

## Upgrading

```bash theme={}
helm upgrade proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --reuse-values \
  --version <new-version>
```

## Uninstall

```bash theme={}
helm uninstall proxy-hopper --namespace proxy-hopper
```