Update docs (#45)

* rename options * create env vars doc * update types * update docs * add readmes
gateweaver · Mar 29, 2024 · 6203c96 · 6203c96
1 parent 903a8e8
commit 6203c96
Show file tree

Hide file tree

Showing 32 changed files with 417 additions and 469 deletions.
diff --git a/README.md b/README.md
@@ -1 +1,95 @@
 # Gateweaver
+
+Welcome to Gateweaver, the open-source API gateway that seamlessly secures your frontend applications' integration with external APIs. Designed with simplicity and protection in mind, Gateweaver enables developers to utilize APIs requiring sensitive keys and tokens without risking exposure on the frontend. Through a straightforward YAML configuration file, users can define endpoints and apply essential policies like CORS, rate limiting, API key management, and JWT authentication, ensuring robust security measures are in place. Start quickly with the Gateweaver CLI or Docker image to streamline your API usage while safeguarding your application.
+
+[Read the full documentation](https://gateweaver.io/docs)
+
+## Getting Started
+
+### Installation
+
+Install the Gateweaver CLI in your project using npm:
+
+```bash
+npm install @gateweaver/cli
+```
+
+or with Yarn:
+
+```bash
+yarn add @gateweaver/cli
+```
+
+or with pnpm:
+
+```bash
+pnpm add @gateweaver/cli
+```
+
+### Configuration
+
+Create a `gateweaver.yml` file in the root of your project:
+
+```yaml title="gateweaver.yml"
+policyDefinitions:
+ cors:
+ origin: "*"
+
+endpoints:
+ - path: "/todos"
+ target:
+ url: "https://example.com/todos"
+ policies:
+ - cors
+```
+
+You can define policies and endpoints in the configuration file. Policies are reusable configurations that can be applied to multiple endpoints. Visit the [Configuration](https://gateweaver.io/docs/category/configuration) page to learn more.
+
+### Environment Variables
+
+To use environment variables in your configuration file, you can use the `${VAR_NAME}` syntax:
+
+```yaml title="gateweaver.yml"
+endpoints:
+ - path: "/todos"
+ target:
+ url: "${API_URL}/todos"
+ policies:
+ - cors
+```
+
+You can set environment variables in a `.env.gateweaver` file in the root of your project:
+
+```bash title=".env.gateweaver"
+NODE_ENV=development
+PORT=8080
+API_URL=https://example.com
+```
+
+Remember to add the `.env.gateweaver` file to your `.gitignore` file to prevent it from being committed to your repository.
+
+### Usage
+
+Run the following command where your `gateweaver.yml` file is located to start the Gateweaver server in watch mode. This will automatically reload the server when the configuration file changes:
+
+```bash
+npx gateweaver start -w
+```
+
+This command will start the Gateweaver server on port 8080 by default. You can specify a different port by setting the `PORT` environment variable in the `.env.gateweaver` file.
+
+Visit the [CLI Commands](https://gateweaver.io/docs/cli) reference page to learn more about the available commands.
+
+### Usage with Docker
+
+You can also run the Gateweaver server using the docker hub image ([gateweaver/server](https://hub.docker.com/r/gateweaver/server/tags)) or github container registry image ([ghcr.io/gateweaver/server](https://github.com/gateweaver/gateweaver/pkgs/container/server)).
+
+The following command mounts the `gateweaver.yml` configuration file and uses the environment variables defined in `.env.gateweaver` to start the Gateweaver server on port 8080.
+
+```bash
+docker run \
+--env-file $(pwd)/.env.gateweaver \
+-v $(pwd)/gateweaver.yml:/app/gateweaver.yml \
+-p 8080:8080 \
+gateweaver/server:0.1.0
+```
diff --git a/docs/docs/configuration/endpoints.md b/docs/docs/configuration/endpoints.md
@@ -58,6 +58,6 @@ An array of policies to apply to the request. The available policies include:
 - [apiKey](/docs/configuration/policies/api-key)
 - [jwt](/docs/configuration/policies/jwt)
 
-You must define the policy in the `policyDefinitions` section of the configuration file before you can reference it in the endpoint.
+You must define the policy in the `policyDefinitions` section of the configuration file before you can reference it in an endpoint.
 
 Powered by [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme)
diff --git a/docs/docs/configuration/environment-variables.md b/docs/docs/configuration/environment-variables.md
@@ -0,0 +1,33 @@
+---
+sidebar_position: 4
+---
+
+# Environment Variables
+
+Gateweaver supports using environment variables in your configuration file. This allows you to define dynamic values that can be set at runtime. You can use the `${VAR_NAME}` syntax to reference environment variables in your configuration file.
+
+## Usage
+
+Here is an example of using environment variables in a configuration file:
+
+```yaml title="gateweaver.yml"
+endpoints:
+ - path: "/todos"
+ target:
+ url: "${API_URL}/todos"
+ transformedRequest:
+ headers:
+ Authorization: "Bearer ${API_TOKEN}"
+```
+
+To use environment variables in your local development environment, you can create a `.env.gateweaver` file in the root of your project:
+
+```bash title=".env.gateweaver"
+NODE_ENV=development
+API_URL=https://example.com
+API_TOKEN=your-api-token
+```
+
+Remember to add the `.env.gateweaver` file to your `.gitignore` file to prevent it from being committed to your repository.
+
+In production, you can set environment variables using your hosting provider's dashboard or CLI.
diff --git a/docs/docs/configuration/policies/_category_.json b/docs/docs/configuration/policies/_category_.json
@@ -1,6 +1,6 @@
 {
  "label": "Policies",
- "position": 3,
+ "position": 4,
  "link": {
  "type": "generated-index"
  }

diff --git a/docs/docs/configuration/policies/api-key.md b/docs/docs/configuration/policies/api-key.md
@@ -6,7 +6,7 @@ sidebar_position: 4
 
 The API Key Policy enables you to secure your endpoints by requiring a valid API key with each request. Gateweaver will verify the API key provided in the `x-api-key` header against a list of hashed API keys defined in the configuration file.
 
-## Configuration Options
+## Options
 
 ### hashes
 

diff --git a/docs/docs/configuration/policies/cors.md b/docs/docs/configuration/policies/cors.md
@@ -6,19 +6,19 @@ sidebar_position: 1
 
 The CORS (Cross-Origin Resource Sharing) policy allows you to tailor how endpoints on your gateway respond to cross-origin requests.
 
-## Configuration Options
+## Options
 
 ### origin
 
 Configures the **Access-Control-Allow-Origin** CORS header.
 
 - `Boolean`: set origin to true to reflect the request origin, as defined by `req.header('Origin')`, or set it to false to disable CORS.
 
-- `String`: set origin to a specific origin. For example if you set it to "http:https://example.com" only requests from "http:https://example.com" will be allowed.
+- `String`: set origin to a specific origin. For example if you set it to "https:https://example.com/" only requests from "https:https://example.com/" will be allowed.
 
 - `RegExp`: set origin to a regular expression pattern which will be used to test request origin. If it's a match, the request origin will be reflected. For example the pattern `/example\\.com$/` will reflect any request that is coming from an origin ending with "example.com".
 
-- `Array`: set origin to an array of valid origins. Each origin can be a String or a RegExp. For example `["http:https://example1.com", /\\.example2\\.com$/]` will accept any request from "http:https://example1.com" or from a subdomain of "example2.com".
+- `Array`: set origin to an array of valid origins. Each origin can be a String or a RegExp. For example `["https:https://example1.com", /\\.example2\\.com$/]` will accept any request from "https:https://example1.com" or from a subdomain of "example2.com".
 
 **Default**: `"*"` (Allows all origins).
 

diff --git a/docs/docs/configuration/policies/jwt.md b/docs/docs/configuration/policies/jwt.md
@@ -6,7 +6,7 @@ sidebar_position: 3
 
 The JWT (JSON Web Token) Authentication policy enables secure access to your API by validating JWT tokens provided in the requests.
 
-## Configuration Options
+## Options
 
 ### secret (Optional)
 

diff --git a/docs/docs/configuration/policies/rate-limit.md b/docs/docs/configuration/policies/rate-limit.md
@@ -6,7 +6,7 @@ sidebar_position: 2
 
 The Rate limit policy allows you to control the rate at which requests to your gateway can be made, preventing abuse and ensuring fair use of resources.
 
-## Configuration Options
+## Options
 
 ### rateLimitBy
 
@@ -18,6 +18,8 @@ Determines what method to use for rate limiting.
 
 **Default**: `"ip"`.
 
+**Important:** When selecting either the jwt or apiKey options, ensure that you have also set up the corresponding [jwt](/docs/configuration/policies/jwt) or [apiKey](/docs/configuration/policies/api-key) policies, respectively, to prevent any unexpected issues.
+
 ### windowMs
 
 Time frame for which requests are checked/remembered in milliseconds.
@@ -70,7 +72,7 @@ Whether to enable support for headers conforming to the [RateLimit header fields
 
 If set to any truthy value, the `Retry-After` header will also be sent on all blocked requests.
 
-**Default**: `"draft-7"`.
+**Default**: `"draft-6"`.
 
 ### skipFailedRequests
 
@@ -101,7 +103,7 @@ policyDefinitions:
  message: "Too many requests, please try again later."
  statusCode: 429
  legacyHeaders: false
- standardHeaders: "draft-7"
+ standardHeaders: "draft-6"
  skipFailedRequests: false
  skipSuccessfulRequests: false
 

diff --git a/docs/docs/configuration/policy-definitions.md b/docs/docs/configuration/policy-definitions.md
@@ -9,7 +9,7 @@ Policies are reusable configurations that can be applied to multiple endpoints.
 ```yaml title="gateweaver.yml"
 policyDefinitions:
  cors:
- origin: "http:https://example.com"
+ origin: "https:https://example.com/"
  methods:
  - "GET"
  - "POST"

diff --git a/docs/docs/deployment.md b/docs/docs/deployment.md
@@ -14,7 +14,9 @@ ENV NODE_ENV=production
 
 This Dockerfile uses the official Gateweaver server image as the base image and copies your `gateweaver.yaml` configuration file into the container. The `NODE_ENV` environment variable is set to `production` to ensure that Gateweaver runs in production mode.
 
-**Note:** Ensure to replace `<version>` with the specific version of Gateweaver you are using. If you have been developing locally using the CLI, it is best to use the same version of `@gateweaver/cli` from your project's `package.json` to maintain compatibility. You can also find the latest version of the Gateweaver server image on the [Docker Hub page](https://hub.docker.com/r/gateweaver/server).
+:::note
+Ensure to replace `<version>` with the specific version of Gateweaver you are using. If you have been developing locally using the CLI, it is best to use the same version of `@gateweaver/cli` from your project's `package.json` to maintain compatibility. You can also find the latest version of the Gateweaver server image on the [Docker Hub page](https://hub.docker.com/r/gateweaver/server).
+:::
 
 ## Deploying with Cloud Services
 
@@ -32,7 +34,7 @@ For an even smoother deployment experience, consider using a cloud service like
 
 4. **Deploy:** Follow the service's instructions to deploy your application. These platforms take care of the complexities of container building and deployment, allowing you to focus on development.
 
-:::tip
+:::note
 Make sure to set the `NODE_ENV` environment variable to `production` to ensure that Gateweaver runs in production mode.
 :::
 

diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -7,7 +7,7 @@ import TabItem from "@theme/TabItem";
 
 # Getting Started
 
-Welcome to the beginning of your journey with Gateweaver!
+Welcome to Gateweaver, the open-source API gateway that seamlessly secures your frontend applications' integration with external APIs. Designed with simplicity and protection in mind, Gateweaver enables developers to utilize APIs requiring sensitive keys and tokens without risking exposure on the frontend. Through a straightforward YAML configuration file, users can define endpoints and apply essential policies like CORS, rate limiting, API key management, and JWT authentication, ensuring robust security measures are in place. Start quickly with the Gateweaver CLI or Docker image to streamline your API usage while safeguarding your application.
 
 ## Installation
 
@@ -81,19 +81,15 @@ Run the following command where your `gateweaver.yml` file is located to start t
 npx gateweaver start -w
 ```
 
-If you would like to use a configuration file with a different name or path, you can specify it using the `--config` or `-c` option:
-
-```bash
-npx gateweaver start -w -c path/to/config.yml
-```
+This command will start the Gateweaver server on port 8080 by default. You can specify a different port by setting the `PORT` environment variable in the `.env.gateweaver` file.
 
 Visit the [CLI Commands](/docs/cli) reference page to learn more about the available commands.
 
 ## Usage with Docker
 
 You can also run the Gateweaver server using the docker hub image ([gateweaver/server](https://hub.docker.com/r/gateweaver/server/tags)) or github container registry image ([ghcr.io/gateweaver/server](https://github.com/gateweaver/gateweaver/pkgs/container/server)).
 
-The following command mounts the `gateweaver.yml` configuration file and uses the environment variables defined in the `.env.gateweaver` file to start the Gateweaver server on port 8080.
+The following command mounts the `gateweaver.yml` configuration file and uses the environment variables defined in `.env.gateweaver` to start the Gateweaver server on port 8080.
 
 ```bash
 docker run \

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -4,11 +4,11 @@ import type * as Preset from "@docusaurus/preset-classic";
 
 const config: Config = {
  title: "Gateweaver",
- tagline: "Gateweaver Documentation",
- favicon: "img/favicon.ico",
+ tagline: "An API Gateway for the frontend.",
+ favicon: "img/logo.png",
 
  // Set the production url of your site here
- url: "https://your-docusaurus-site.example.com",
+ url: "https://gateweaver.io",
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  baseUrl: "/",
@@ -54,7 +54,7 @@ const config: Config = {
  title: "Gateweaver",
  logo: {
  alt: "Gateweaver Logo",
- src: "img/logo.svg",
+ src: "img/logo.png",
  },
  items: [
  {
@@ -77,39 +77,51 @@ const config: Config = {
  title: "Docs",
  items: [
  {
- label: "Tutorial",
- to: "/docs/intro",
+ label: "Getting Started",
+ to: "/docs/getting-started",
  },
- ],
- },
- {
- title: "Community",
- items: [
  {
- label: "Stack Overflow",
- href: "https://stackoverflow.com/questions/tagged/docusaurus",
+ label: "Configuration",
+ to: "/docs/configuration",
  },
  {
- label: "Discord",
- href: "https://discordapp.com/invite/docusaurus",
+ label: "CLI Reference",
+ to: "/docs/cli",
  },
  {
- label: "Twitter",
- href: "https://twitter.com/docusaurus",
+ label: "Deployment",
+ to: "/docs/deployment",
  },
  ],
  },
+ // {
+ // title: "Community",
+ // items: [
+ // {
+ // label: "Stack Overflow",
+ // href: "https://stackoverflow.com/questions/tagged/gateweaver",
+ // },
+ // {
+ // label: "Discord",
+ // href: "https://discordapp.com/invite/gateweaver",
+ // },
+ // {
+ // label: "Twitter",
+ // href: "https://twitter.com/gateweaver",
+ // },
+ // ],
+ // },
  {
  title: "More",
  items: [
  {
  label: "GitHub",
- href: "https://github.com/facebook/docusaurus",
+ href: "https://github.com/gateweaver/gateweaver",
  },
  ],
  },
  ],
- copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+ copyright: `Copyright © ${new Date().getFullYear()} Gateweaver. Built with Docusaurus.`,
  },
  prism: {
  theme: prismThemes.github,