Skip to content

Commit 561ff6f

Browse files
TristanSpeakEasyTristanSpeakEasy
committed
docs: add documentation for using proxy plus supporting changes
1 parent f9bf317 commit 561ff6f

File tree

5 files changed

+152
-4
lines changed

5 files changed

+152
-4
lines changed

‎.github/workflows/build-docker.yaml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Create and publish a Docker image
2+
3+
on:
4+
push:
5+
tags:
6+
- "*"
7+
8+
env:
9+
REGISTRY: ghcr.io
10+
IMAGE_NAME: ${{ github.repository }}
11+
12+
jobs:
13+
build-and-push-image:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
packages: write
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v3
22+
23+
- name: Log in to the Container registry
24+
uses: docker/[email protected]
25+
with:
26+
registry: ${{ env.REGISTRY }}
27+
username: ${{ github.actor }}
28+
password: ${{ secrets.GITHUB_TOKEN }}
29+
30+
- name: Extract metadata (tags, labels) for Docker
31+
id: meta
32+
uses: docker/[email protected]
33+
with:
34+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
35+
36+
- name: Build and push Docker image
37+
uses: docker/[email protected]
38+
with:
39+
context: .
40+
push: true
41+
tags: ${{ steps.meta.outputs.tags }}
42+
labels: ${{ steps.meta.outputs.labels }}

‎README.md

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,99 @@
11
# speakeasy-proxy
22

3-
## Build Docker Image
3+
## Overview
4+
5+
The Speakeasy Proxy is a simple reverse proxy that allows capturing of API traffic for use with the Speakeasy Platform.
6+
7+
The proxy is currently designed to be single use, and will only capture HTTP traffic for a single API, this means that it should not be used as a replacement for traditional reverse proxies or API gateways and instead used in conjunction with them.
8+
9+
The proxy requires an OpenAPI document to be provided which helps to associate the captured traffic with the API.
10+
11+
## Usage
12+
13+
### Configuration
14+
15+
The proxy is configured using a YAML file. The following is an example configuration:
16+
17+
```yaml
18+
downstreamBaseURL: http://localhost:8001
19+
apiID: proxy-test
20+
versionID: "0.0.1"
21+
openAPIDocs:
22+
- ./httpbin.yaml
23+
```
24+
25+
The available configuration options are:
26+
27+
| Option | Description | Required | Default | Location |
28+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | -------------------- | --------------------------------------------- |
29+
| `downstreamBaseURL` | The base URL of the downstream API to forward traffic to | :heavy_check_mark: | `-` | Config File or `DOWNSTREAM_BASE_URL` env var |
30+
| `SPEAKEASY_API_KEY` | The Speakeasy API Key (retrieved from the [Speakeasy Platform](https://app.speakeasyapi.dev/)) to use when communicating with Speakeasy | :heavy_check_mark: | `-` | `SPEAKEASY_API_KEY` env var only |
31+
| `apiID` | The ID of the API to capture traffic for | :heavy_check_mark: | `-` | Config File or `SPEAKEASY_API_ID` env var |
32+
| `versionID` | The Version of the API version to capture traffic for | :heavy_check_mark: | `-` | Config File or `SPEAKEASY_VERSION_ID` env var |
33+
| `openAPIDocs` | A list of OpenAPI documents to use to associate captured traffic with the API. If multiple are provided they are merged with the [Speakeasy Merge Functionality](https://github.com/speakeasy-api/speakeasy/blob/main/docs/merge.md) | :heavy_minus_sign: | `["./openapi.yaml"]` | Config File or `OPENAPI_DOCS` env var |
34+
| `configLocation` | The location of the configuration file to use | :heavy_minus_sign: | `./config.yaml` | `CONFIG_LOCATION` env var only |
35+
| `port` | The port to listen on | :heavy_minus_sign: | `3333` | Config File or `PORT` env var |
36+
37+
### Running the Proxy
38+
39+
The proxy can be built and run either as a binary or as a Docker image currently, allowing for a number of different deployment scenarios, such as running locally, in simple container based cloud environments or in more complex container orchestration environments like Kubernetes.
40+
41+
To run the proxy follow the steps below:
42+
43+
1. Create and obtain an API Key from the [Speakeasy Platform](https://app.speakeasyapi.dev/) either by creating a new Workspace or using an existing one.
44+
2. Request access to the Speakeasy Request Capture Beta in our [Slack Community](https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1eih279u9-uahunmIavQZJpiGmEIqYbA)
45+
3. Create a configuration file (see [Configuration](#configuration) for details) ie. `./config.yaml` or set the required environment variables.
46+
4. Create or use an existing OpenAPI document for the API you wish to capture traffic for and make sure it is accessible to the proxy ie. `./openapi.yaml`
47+
5. Run the proxy either as a binary or as a Docker image (see [Running](#running) for details)
48+
6. View the captured traffic in the [Speakeasy Platform](https://app.speakeasyapi.dev/) in your worksspace.
49+
50+
### Testing the Proxy locally
51+
52+
If you just want to test our the proxy locally, there are a few different ways you can do this:
53+
54+
1. The first is via our [Speakeasy CLI tool](https://github.com/speakeasy-api/speakeasy) (Documentation [here](https://github.com/speakeasy-api/speakeasy/blob/main/docs/proxy.md)) which allows running the proxy locally and capturing traffic for any HTTP (HTTPS terminatation not supported) API easily using simple command line options to configure the proxy.
55+
1. Request access to the Speakeasy Request Capture Beta in our [Slack Community](https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1eih279u9-uahunmIavQZJpiGmEIqYbA)
56+
2. Authenticate the CLI tool using the `speakeasy auth login` command.
57+
3. Run the proxy using the Speakeasy CLI tool: `speakeasy proxy --api-id {API_ID} --version-id {VERSION_ID} --schema {OPENAPI_DOC_LOCATION} --downstream {DOWNSTREAM_BASE_URL}`
58+
4. Use the API you are capturing traffic for.
59+
5. View the captured traffic in the [Speakeasy Platform](https://app.speakeasyapi.dev/) in your workspace.
60+
2. The second way is using the [httpbin](https://httpbin.org/) service as a test API to test it out, which we have setup to run using Docker Compose. Instruction for this are as follows:
61+
1. Follow steps 1-2 from [Running the Proxy](#running-the-proxy) above.
62+
2. Start the httpbin service and proxy using docker-compose: `SPEAKEASY_API_KEY='{API_KEY_HERE}' docker-compose up`
63+
3. Access the httpbin service via the proxy at <http://localhost:3333> and use some of the endpoints to generate traffic.
64+
4. View the captured traffic in the [Speakeasy Platform](https://app.speakeasyapi.dev/) in your workspace.
65+
66+
## Building
67+
68+
### Build Binary
69+
70+
```bash
71+
go build -o speakeasy-proxy
72+
```
73+
74+
### Build Docker Image
475

576
```bash
677
docker build -t speakeasy-proxy .
778
```
879

9-
## Run Docker Image
80+
## Running
81+
82+
### Run Binary
83+
84+
```bash
85+
SPEAKEASY_API_KEY='{API_KEY_HERE}' ./speakeasy-proxy
86+
```
87+
88+
### Run Docker Image
89+
90+
If built locally:
1091

1192
```bash
1293
docker run --network="host" -p 3333:3333 -v $(pwd)/config.yaml:/config.yaml -v $(pwd)/httpbin.yaml:/httpbin.yaml -e SPEAKEASY_API_KEY='{API_KEY_HERE}' speakeasy-proxy
13-
```
94+
```
95+
96+
If using our pre-built image:
97+
98+
```bash
99+
```

‎docker-compose.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,18 @@ services:
44
image: kennethreitz/httpbin
55
ports:
66
- "8001:80"
7+
speakeasy-proxy:
8+
build:
9+
context: .
10+
dockerfile: Dockerfile
11+
environment:
12+
- CONFIG_LOCATION=./example-config.yaml
13+
- OPENAPI_DOCS=./httpbin.yaml
14+
- SPEAKEASY_API_KEY=${SPEAKEASY_API_KEY}
15+
volumes:
16+
- ./example-config.yaml:/example-config.yaml
17+
- ./httpbin.yaml:/httpbin.yaml
18+
ports:
19+
- "3333:3333"
20+
depends_on:
21+
- httpbin

‎example-config.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
downstreamBaseURL: http://httpbin:80
2+
apiID: proxy-test
3+
versionID: "0.0.1"
4+
openAPIDocs:
5+
- ./httpbin.yaml

‎internal/config/config.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ type Config struct {
1717
ApiID string `yaml:"apiID" env:"SPEAKEASY_API_ID" validate:"required"`
1818
VersionID string `yaml:"versionID" env:"SPEAKEASY_VERSION_ID" validate:"required"`
1919
OpenAPIDocs []string `yaml:"openAPIDocs" env:"OPENAPI_DOCS" validate:"min=1" default:"[\"./openapi.yaml\"]"`
20-
ConfigLocation string `yaml:"configLocation" env:"CONFIG_LOCATION" validate:"required" default:"./config.yaml"`
20+
ConfigLocation string `env:"CONFIG_LOCATION" validate:"required" default:"./config.yaml"`
2121
}
2222

2323
func Load() (*Config, error) {

0 commit comments

Comments
 (0)