> For the complete documentation index, see [llms.txt](https://docs.openbotauth.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbotauth.org/proxy/ghcr.md).

# GitHub Container Registry

Run the OpenBotAuth Proxy using GitHub Container Registry (GHCR) images.

**Image:** [ghcr.io/openbotauth/openbotauth-proxy](https://github.com/OpenBotAuth/openbotauth/pkgs/container/openbotauth-proxy)

## Why GHCR?

* **GitHub integration** - Works seamlessly with GitHub Actions and workflows
* **Same source** - Images built directly from GitHub repository
* **Alternative registry** - Fallback if Docker Hub is unavailable

## Quick Start

```bash
docker run -p 8088:8088 ghcr.io/openbotauth/openbotauth-proxy
```

## Supported Platforms

* `linux/amd64` - Intel/AMD 64-bit
* `linux/arm64` - ARM 64-bit (Apple Silicon, AWS Graviton)

## Pull Image

```bash
# Latest version
docker pull ghcr.io/openbotauth/openbotauth-proxy

# Specific version
docker pull ghcr.io/openbotauth/openbotauth-proxy:0.1.5

# Latest tag
docker pull ghcr.io/openbotauth/openbotauth-proxy:latest
```

## Authentication

GHCR images are public, but for private images or higher rate limits:

```bash
# Login with GitHub token
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
```

## Configuration

Same environment variables as Docker Hub image:

| Variable              | Default                                   | Description                     |
| --------------------- | ----------------------------------------- | ------------------------------- |
| `PORT`                | `8088`                                    | Proxy listen port               |
| `UPSTREAM_URL`        | `http://localhost:8080`                   | Backend server URL              |
| `OBA_VERIFIER_URL`    | `https://verifier.openbotauth.org/verify` | Verifier endpoint               |
| `OBA_MODE`            | `observe`                                 | `observe` or `require-verified` |
| `OBA_TIMEOUT_MS`      | `5000`                                    | Verifier timeout (ms)           |
| `OBA_PROTECTED_PATHS` | `/protected`                              | Comma-separated protected paths |

## Usage Examples

### Basic Usage

```bash
docker run -p 8088:8088 ghcr.io/openbotauth/openbotauth-proxy
```

### With Configuration

```bash
docker run -p 8088:8088 \
  -e UPSTREAM_URL=http://backend:3000 \
  -e OBA_MODE=require-verified \
  -e OBA_PROTECTED_PATHS=/api,/content \
  ghcr.io/openbotauth/openbotauth-proxy
```

## Docker Compose

```yaml
version: '3.8'

services:
  proxy:
    image: ghcr.io/openbotauth/openbotauth-proxy
    ports:
      - "8088:8088"
    environment:
      - UPSTREAM_URL=http://backend:3000
      - OBA_MODE=observe
    depends_on:
      - backend

  backend:
    image: your-backend-image
    expose:
      - "3000"
```

## GitHub Actions

### Use in Workflows

```yaml
name: Deploy with OBA Proxy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    services:
      oba-proxy:
        image: ghcr.io/openbotauth/openbotauth-proxy
        ports:
          - 8088:8088
        env:
          UPSTREAM_URL: http://localhost:3000
          OBA_MODE: observe

    steps:
      - uses: actions/checkout@v4

      - name: Start backend
        run: npm start &

      - name: Test through proxy
        run: curl http://localhost:8088/.well-known/health
```

### Build and Deploy with GHCR

```yaml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Pull OBA Proxy
        run: docker pull ghcr.io/openbotauth/openbotauth-proxy

      - name: Deploy
        run: |
          docker run -d \
            -p 8088:8088 \
            -e UPSTREAM_URL=http://backend:3000 \
            ghcr.io/openbotauth/openbotauth-proxy
```

## Kubernetes with GHCR

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: oba-proxy
spec:
  replicas: 2
  selector:
    matchLabels:
      app: oba-proxy
  template:
    metadata:
      labels:
        app: oba-proxy
    spec:
      containers:
        - name: oba-proxy
          image: ghcr.io/openbotauth/openbotauth-proxy
          ports:
            - containerPort: 8088
          env:
            - name: UPSTREAM_URL
              value: "http://backend-service:3000"
            - name: OBA_MODE
              value: "observe"
```

For private images, add imagePullSecrets:

```yaml
spec:
  imagePullSecrets:
    - name: ghcr-secret
  containers:
    - name: oba-proxy
      image: ghcr.io/openbotauth/openbotauth-proxy
```

## Comparing Registries

| Feature        | Docker Hub                      | GHCR                                    |
| -------------- | ------------------------------- | --------------------------------------- |
| URL            | `hammadtariq/openbotauth-proxy` | `ghcr.io/openbotauth/openbotauth-proxy` |
| Auth           | Docker Hub account              | GitHub token                            |
| Rate Limits    | 100 pulls/6hr (anon)            | 1000+ pulls/hr                          |
| GitHub Actions | Manual login                    | Native integration                      |
| Same Image     | Yes                             | Yes                                     |

## Health Check

```bash
curl http://localhost:8088/.well-known/health
```

Response:

```json
{
  "status": "ok",
  "service": "openbotauth-proxy",
  "upstream": "http://backend:3000",
  "verifier": "https://verifier.openbotauth.org/verify",
  "mode": "observe"
}
```

## Troubleshooting

### Rate limit exceeded

Login to GHCR for higher limits:

```bash
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
```

### Image not found

Verify the image exists:

```bash
docker manifest inspect ghcr.io/openbotauth/openbotauth-proxy
```

### Permission denied

For private images, ensure your token has `read:packages` scope.

## Links

* **GHCR:** <https://github.com/OpenBotAuth/openbotauth/pkgs/container/openbotauth-proxy>
* **GitHub:** <https://github.com/OpenBotAuth/openbotauth>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.openbotauth.org/proxy/ghcr.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.