Updated readme with wiretap docs.

Signed-off-by: Dave Shanley <[email protected]>
pb33f · Aug 1, 2023 · 4117e37 · 4117e37
1 parent a1bd7dd
commit 4117e37
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 43 deletions.
diff --git a/.github/wiretap-hero.png b/.github/wiretap-hero.png
diff --git a/README.md b/README.md
@@ -1,71 +1,114 @@
 # wiretap
 
+![logo](.github/wiretap-hero.png)
 
 A local and pipeline based tool to sniff API request and responses from clients and servers
 to detect OpenAPI contract violations and compliance.
 
 A shift left tool, for those who want to know if their applications
 are actually compliant with an API.
 
-This is an early tool and in active development.
+This is an early tool and in active development, Why not try it out and give us some feedback?
 
-Probably best to leave this one alone for now, come back later
-when it's a little more baked.
+![](https://github.com/pb33f/wiretap/blob/main/.github/assets/wiretap-preview.gif)
 
+---
+# Read the quickstart guide
 
-![](https://github.com/pb33f/wiretap/blob/main/.github/assets/wiretap-preview.gif)
+[🚀 Quick Start Guide 🚀](https://pb33f.io/wiretap/quickstart/)
+
+---
+# Install wiretap for your platform
+
+## Installing using homebrew
 
-## Configuring paths & rewriting them. 
+The easiest way to install `wiretap` is to use **[homebrew](https://brew.sh)** if you're on OSX or Linux.
 
-Provide a configuration for path rewriting via the wiretap config.
+We have our own tap available that gives the latest and greatest version.
 
-This uses the same syntax for path rewriting as the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)
+```shell
+brew install pb33f/taps/wiretap
+```
+
+---
 
-Paths can be matched by globs and then individual segments can be matched and re-written.
+## Installing using npm or yarn
 
-```yaml
-paths:
-  /pb33f/*/test/**:
-    target: localhost:80
-    pathRewrite:
-      '^/pb33f/(\w+)/test/': ''
+Building a JavaScript / TypeScript application? No problem, grab your copy of `wiretap` using your preference
+of **[yarn](https://yarnpkg.com/)** or **[npm](https://npmjs.com)**.
+
+```shell
+yarn add global @pb33f/wiretap
 ```
 
-## Dropping certain headers
+or...
+
+```shell
+npm -i -g @pb33f/wiretap
+```
+
+---
+
+## Installing using cURL
+
+Do you want to use `wiretap` in a linux only or CI/CD pipeline or workflow? Or you don't want to/can't use
+a package manager like brew?
+
+No problem. Use **cURL** to download and run our installer script.
+
+```shell
+curl -fsSL https://pb33f.io/wiretap/install.sh | sh
+```
 
-To prevent certain headers from being proxies, you can drop them using the `headers` config property and the `drop` property
-which is an array of headers to drop from all outbound requests..
+---
 
-```yaml
-headers:
-  drop:
-    - Origin
-```    
+## Installing/running using Docker
 
-## Configuring static paths
+Love containers? Don't want to install anything? No problem, use our Docker image.
+
+```shell
+docker pull pb33f/wiretap
+```
+
+```
+docker run -p 9090:9090 -p 9091:9091 -p 9092:9092 --rm -v  \
+    $PWD:/work:rw pb33f/wiretap -u https://somehostoutthere.com
+```
+
+We enable the following default ports `9090`, `9091`, and `9092` for the daemon, monitor, and websockets used
+by [ranch](https://github.com/pb33f/ranch) respectively.
+
+---
+
+## Installing on Windows
+
+To grab your copy of `wiretap` for Windows, you can pull it from the
+**[latest releases on github](https://github.com/pb33f/wiretap/releases)**
+and download the Windows version for your CPU type.
+
+---
+
+# Running wiretap
+
+To get up and running with the absolute defaults (which is to sniff all traffic on port 9090)
+and proxy to `https://api.pb33f.com` you can run the following command.
+
+```shell
+wiretap -u https://api.pb33f.com
+```
 
-Running a single page application? Need certain paths to always be caught and forwarded to your SPA? Configure
-static paths to be caught and forwarded to your SPA.
+## Adding an OpenAPI contract
 
-```yaml
-staticDir: ui/dist
-staticIndex: index.html
-staticPaths:
-  - /my-app/*
-  - /another-app/somewhere/*
+```shell
+wiretap -u https://api.pb33f.com -s my-openapi-spec.yaml
 ```
 
-## Command Line Interface
+# Documentation
 
-### Available Flags
+- 🚀 [Quick Start](https://pb33f.io/wiretap/quickstart/) 🚀
+- [Installing](https://pb33f.io/wiretap/quickstart/)
+- [Configuring](https://pb33f.io/wiretap/configuring/)
+- [Monitor UI](https://pb33f.io/wiretap/monitor/)
+- [Serving static content](https://pb33f.io/wiretap/static-content/)
+- [GiftShop example API](https://pb33f.io/wiretap/giftshop-api/)
 
-| Shortcut | Flag             | Description                                                                                |
-|----------|------------------|--------------------------------------------------------------------------------------------|
-| `-u`     | `--url`          | Redirect URL for wiretap to send traffic to.                                               |
-| `-s`     | `--spec`         | Path to the OpenAPI Specification to use.                                                  |
-| `-p`     | `--port`         | Port on which to listen for API traffic. (default is `9090`)                               |
-| `-m`     | `--monitor-port` | Port on which to serve the monitor UI. (default is `9091`)                                 |
-| `-d`     | `--delay`        | Set a global delay for all API requests in milliseconds. (default is `0`)                  |
-| `-c`     | `--config`       | Location of wiretap configuration file to use (default is `.wiretap` in current directory) |
-| `-t`     | `--static`       | Location of static files to serve along with API requests (simulate real app deployment)   |
-| `-i`     | `--static-index` | Index file to serve for root static requests and all static paths (default is index.html)  |