# Google Cloud Run proxy

> A small Cloud Run service behind your external Application Load Balancer, answering the one path the dashboard issued and forwarding the browser SDK's calls.

Last updated: 2026-09-25

A small Cloud Run service that your external Application Load Balancer routes one path to. It answers the path the dashboard issued, on your own domain, and forwards only the browser SDK's submissions to Fingerly. It is not an open proxy: the upstream is a constant in the code, and every other path and method is refused. Version 1.0.0.

> **Warning:** Firebase Hosting rewrites to Cloud Run are not supported. Firebase documents no header carrying the visitor's address to Cloud Run that the visitor cannot forge, so the proxy could not tell Fingerly who the visitor is. Use a load balancer, or a [hosted subdomain](https://docs.fingerly.io/docs/hosted-subdomain).

## Set up

### Step 1: Create the proxy

In the dashboard, open **Integration > Proxy keys** and choose **New proxy**. Pick the environment of the public key it will forward, and **Google Cloud** under **How it runs**. Copy the [proxy key](https://docs.fingerly.io/docs/proxy-integrations#proxy-keys) it shows once, and note the path it issued, such as `/k7x2qm4a`.

The dashboard then prints the steps below, filled in with your proxy's own path and key. They stay under **Show setup** in the proxy's menu, without the key, which is never shown again.

### Step 2: Save the service

Save `server.mjs` in an empty folder, with its `package.json` beside it. Buildpacks build the service from `package.json`, so no Dockerfile is needed. It needs Node 20 or newer.

`server.mjs` is a small Node service with no dependencies: the built-in HTTP server and `fetch`. It reads `FINGERLY_PROXY_KEY`, `FINGERLY_PATH`, `FINGERLY_CLIENT_IP_SOURCE` and `PORT` (default `8080`), and refuses to start when the address source is not one it knows. The dashboard prints it; copy it from there.

```json package.json
{
  "name": "first-party-relay",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.mjs"
  },
  "engines": {
    "node": ">=20"
  }
}
```

### Step 3: Store the proxy key

In Secret Manager, readable by the service's runtime service account.

```bash Terminal
printf '%s' 'fly_px_production_…' | gcloud secrets create first-party-relay-key --data-file=-
gcloud secrets add-iam-policy-binding first-party-relay-key \
  --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor
```

### Step 4: Deploy

From the folder. The ingress setting means only your load balancer can reach the service.

```bash Terminal
gcloud run deploy site-relay --source . --region=europe-west1 \
  --ingress=internal-and-cloud-load-balancing --allow-unauthenticated \
  --set-env-vars=FINGERLY_PATH=/k7x2qm4a \
  --set-secrets=FINGERLY_PROXY_KEY=first-party-relay-key:latest
```

### Step 5: Add it to your load balancer

A serverless network endpoint group and a backend service. Use the scheme your load balancer already uses: `EXTERNAL_MANAGED` for the global external Application Load Balancer, `EXTERNAL` for the classic one.

```bash Terminal
gcloud compute network-endpoint-groups create site-relay-neg \
  --region=europe-west1 --network-endpoint-type=serverless \
  --cloud-run-service=site-relay
gcloud compute backend-services create site-relay-backend \
  --global --load-balancing-scheme=EXTERNAL_MANAGED
gcloud compute backend-services add-backend site-relay-backend \
  --global --network-endpoint-group=site-relay-neg \
  --network-endpoint-group-region=europe-west1
```

### Step 6: Route the path to it

In the URL map that serves your site. If your host has no path matcher yet:

```bash Terminal
gcloud compute url-maps add-path-matcher URL_MAP --global \
  --path-matcher-name=site --default-service=YOUR_SITE_BACKEND \
  --new-hosts=www.example.com --path-rules=/k7x2qm4a=site-relay-backend
```

If it has one, add a path rule for `/k7x2qm4a` with the backend `site-relay-backend` to it instead: export the map with `gcloud compute url-maps export`, add the rule and import it back, or use **Load balancing > your load balancer > Edit > Routing rules** in the console.

### Step 7: Point the browser SDK at the path

```ts fingerly.ts
import { load } from '@fingerly/web-js'

const fingerly = await load({
  apiKey: 'fly_pk_production_…',
  endpoints: '/k7x2qm4a',
})
```

The SDK posts both of its calls to the path exactly as given. Once pages use it, the proxy's row in **Proxy keys** shows it last seen, running `gcp-cloud-run/1.0.0`, with its requests over the last 30 days.

## How the visitor's address is trusted

The load balancer appends `<client-ip>,<load-balancer-ip>` to `X-Forwarded-For`, and vouches for nothing before them. The service sends the second-to-last entry as `x-fingerly-client-ip`, so entries a visitor writes on the left are ignored. That is its default address source, `xff:2`.

It holds only while every request arrives through the load balancer, which is what `--ingress=internal-and-cloud-load-balancing` enforces. If you put another proxy in front of the load balancer, the second-to-last entry is that proxy: set `FINGERLY_CLIENT_IP_SOURCE` to match, as described for the [container](https://docs.fingerly.io/docs/proxies/container#how-the-visitor-s-address-is-trusted).

## What it sends and relays

Upstream, to `https://api.fingerly.io/api/v1/ingest` and nowhere else, on headers built from scratch: `content-type`, `x-api-key`, `Idempotency-Key` when present, and the `x-fingerly-*` headers the proxy sets itself (the proxy key, the visitor's address, the page origin, the user agent and `x-fingerly-proxy-version: gcp-cloud-run/1.0.0`). Cookies, `Authorization` and any `x-fingerly-*` header a visitor sends never leave.

Other methods answer `405` with `Allow: POST`, and other paths `404`. Bodies over 1 MiB are refused with `413`, redirects are not followed, and a missing or malformed key answers `503` rather than forwarding anything. With `FINGERLY_PATH` unset, the service answers `404` to everything.

Back to the page: the API's status and body, with only `content-type`, `x-request-id`, `ratelimit-limit`, `ratelimit-remaining` and `retry-after`, plus `cache-control: no-store`. Nothing relayed names Fingerly.