# Nginx gateway recipe

URL: https://briq.cloud/cookbook/nginx

> A gateway (reverse proxy): one URL for several briqs of a stack, routed by path (/api/ to the back end, / to the front end). One origin for the browser, nothing to change in the apps.

Tags: app, proxy

Guide:

- [Run a GitHub repo](https://briq.cloud/docs/guides/run-a-github-repo.md): An app from a repo, running with a URL. The briq downloads the code itself, and nothing is built on your side.

## Run it

MCP:

```ts
briq_run({
  recipe: "nginx",
  params: {
    "routes": {
      "/": "app:8080"
    },
    "size": "nano"
  },
  wait: true
})
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "nginx",
    "params": {
      "routes": {
        "/": "app:8080"
      },
      "size": "nano"
    },
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "GATEWAY_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Parameters

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `routes` | record | { "/prefix/": "briq:port" } | {"/":"app:8080"} | Path prefix → "briq:port" in the same stack, e.g. { "/api/": "backend:8080", "/": "frontend:8080" }. The longest prefix wins and matches the start of a path (/docs also takes /docs-old; end it with / for a folder); the path is passed on whole (/api/users stays /api/users). Run it after those briqs exist |
| `size` | enum | nano, small | "nano" | — |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `GATEWAY_URL` | `http://gateway.<stack>.internal` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| gateway | `nginx:1-alpine` | 80 | nano | — |

## When to use it

* An app in several briqs (front end, back end, database), opened at one URL.
* A front end that calls its API at `/api/…`: one origin, so no CORS and no API address to build in.

## Tips

* **Run it last**: it reads the addresses of the briqs it routes to, and waits for them to run.
* **Routes are path prefixes**: `{ "/api/": "backend:8000", "/": "frontend:8080" }`. The longest
  wins, and the path is passed on whole.
* **End a prefix with `/`** to match a folder only: `/docs` also takes `/docs-old`.
* **Name the briqs behind it**: run them with `name: "backend"` and `name: "frontend"`.
* **Expose only the gateway**: the briqs behind it stay private. Its URL is `gateway-…`.
* **Listen on `::`** behind it: it reaches them over the private network, which is IPv6.
* **A 502 for a few seconds** means a briq behind it is still starting, after a wake for example.
* **Host, `X-Forwarded-Host` and WebSockets** go through.
* **Step by step**: [Run a GitHub repo](https://briq.cloud/docs/guides/run-a-github-repo#several-services).