finos · JamieSlome · Dec 12, 2023 · Oct 27, 2023 · Oct 27, 2023 · Oct 31, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,6 +11,9 @@ Before making a contribution, please take the following steps:
 4. Fork the project repository and prepare your proposed contribution.
 5. Submit a pull request.
 
+If this is your first time contributing to open source projects on GitHub, it's recommended that you
+follow the [contribution guide for first-time contributors](https://github.com/firstcontributions/first-contributions#first-contributions).
+
 NOTE: All contributors must have a contributor license agreement (CLA) on file with FINOS before their pull requests will be merged. Please review the FINOS [contribution requirements](https://finosfoundation.atlassian.net/wiki/spaces/FINOS/pages/75530375/Contribution+Compliance+Requirements) and submit (or have your employer submit) the required CLA before submitting a pull request.
 
 ## Governance

diff --git a/README.md b/README.md
@@ -46,234 +46,40 @@ Git Proxy deploys custom push protections and policies on top of Git. It is a hi
 Git Proxy is built with a developer-first mindset. By presenting simple-to-follow remediation instructions in the CLI/Terminal, it minimises the friction of use and adoption, and keeps developers focused on what matters; committing and pushing code.
 
 
-## Installation
+## Getting Started 🚀
 
-To install Git Proxy, you must first install [Node.js](https://nodejs.org/en/download). Then, use the [npm](https://www.npmjs.com/) package manager:
+Install & run git-proxy (requires [Nodejs](https://nodejs.org/en/download/)):
 
 ```bash
-npm install -g @finos/git-proxy
+$ npx -- @finos/git-proxy
 ```
 
-To install a specific version of Git Proxy, append the version to the end of the `install` command:
+Clone a repository, set the remote to the Git Proxy URL and push your changes:
 
 ```bash
-npm install -g @finos/git-proxy@1.1.0
+$ git clone https://github.com/octocat/Hello-World.git && cd Hello-World
+# The below command is using the GitHub official CLI to fork the repo that is cloned.
+# You can also fork on the GitHub UI. For usage details on the CLI, see https://github.com/cli/cli
+$ gh repo fork
+✓ Created fork yourGithubUser/Hello-World
+...
+$ git remote add proxy http://localhost:8000/yourGithubUser/Hello-World.git
+$ git push proxy master
 ```
 
-## Run Git Proxy ⚡
+Using the default configuration, Git Proxy intercepts the push and _blocks_ it. To enable code pushing to your fork via Git Proxy, add your repository URL into the Git Proxy config file (`proxy.config.json`). For more information, refer to [our documentation](https://git-proxy.finos.org).
 
-Once you have followed the [installation](#installation) steps, run Git Proxy with:
+## Documentation
+For detailed step-by-step instructions for how to install, deploy & configure Git Proxy and
+customize for your environment, see the [project's documentation](https://git-proxy.finos.org/docs/):
 
-```bash
-git-proxy
-```
-
-Alternatively, if you prefer the magic of [npx over npm](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/), you can run Git Proxy with:
-
-```bash
-npx --package=@finos/git-proxy@1.1.0 -- git-proxy # No installation required...
-```
-
-## Quickstart 🚀
-
-#### 1. Run Git Proxy with simple config
-
-Create a `proxy.config.json` in a workspace with the following:
-
-```json
-{
-    "authorisedList": [
-    {
-      "project": "<YOUR-GITHUB-USERNAME>",
-      "name": "git-proxy",
-      "url": "https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git"
-    }
-  ],
-}
-```
-
-Then run Git Proxy and load your `proxy.config.json` configuration file from your workspace:
-
-```bash
-npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./proxy.config.json
-```
-
-#### 2. Pick a repository
-
-Git Proxy sits between the local clone of your repository and its remote upstream. Essentially, instead of communicating directly with the **live** version of your repository, you configure your local clone to speak with Git Proxy first.
-
-For demonstration purposes, we recommend 👉 [forking Git Proxy](https://github.com/finos/git-proxy/fork) and cloning the repository to your PC:
-
-```bash
-git clone https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git
-```
-
-Pretty meta, huh? Testing Git Proxy on Git Proxy...
-
-#### 3. Introduce Git Proxy to your clone
-
-Navigate into your test-bed repository on your PC:
-
-```bash
-cd ./git-proxy
-```
-
-By default the clone of your repository will communicate with GitHub. To change this, so that your local copy of the repository speaks with Git Proxy, run:
-
-```bash
-git remote set-url origin http://localhost:8000/<YOUR-GITHUB-USERNAME>/git-proxy.git
-```
-
-#### 4. Make some changes to the codebase
-
-Open up the `README.md` and turn this frown upside-down: ☹️
-
-Once you've cheered up our friend above, run:
-
-```bash
-git add README.md
-git commit -m "fix: turn frown upside-down"
-```
-
-####  5. Push your changes via Git Proxy
-
-```bash
-git push
-```
-
-Git Proxy will prompt the entry of your git credentials. These credentials are your GitHub username and a [Personal Access Token](https://github.com/settings/tokens). For the ability to push and pull code through Git Proxy, you will only require the `public_repo` scope.
-
-Git Proxy will reprompt you for credentials each time you push. To automatically re-use your credentials, you can run:
-
-```bash
-git config --global credential.helper osxkeychain # MacOS
-
-git config --global credential.helper manager # Windows
-
-git config --global credential.helper store # Linux
-```
-
-#### 6. Success
-
-Immediately after a push, you should receive the following message in your terminal:
-
-```bash
-remote:
-remote: Git Proxy has received your push:
-remote: 
-remote: http://localhost:8080/requests/000000__b12557    
-remote:
-```
-
-## Configuring Git Proxy ⚙️
-
-By default, Git Proxy ships with an out-of-the-box configuration.
-
-To customise your Git Proxy configuration, create a `proxy.config.json` in your directory.
-
-To specify a different file name for your Git Proxy configuration, use:
-
-```bash
-git-proxy --config ./config.json
-```
-
-Or with npx:
-
-```bash
-npx -- @finos/git-proxy --config ./config.json
-```
-
-## Know Your Configuration (KYC) ✅
-
-To check that your Git Proxy configuration is valid, run:
-
-```bash
-git-proxy --validate
-```
-
-To validate your configuration at a custom file location, run:
-
-```bash
-git-proxy --validate --config ./config.json
-```
+- [Quickstart](https://git-proxy.finos.org/docs/category/quickstart/)
+- [Installation](https://git-proxy.finos.org/docs/installation)
+- [Configuration](https://git-proxy.finos.org/docs/configuration)
 
 ## Contributing
 
-Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**.
-
-<br />
-
-<a src="https://github.com/finos/git-proxy/fork">
-<img align="right" width="300" src="https://firstcontributions.github.io/assets/Readme/fork.png" alt="fork this repository" />
-</a>
-
-#### Fork the repository
-
-Click on the **fork** button at the top of the page. This will create a copy of this repository under your GitHub account.
-
-<br />
-<br />
-
-#### Clone the repository
-
-<img align="right" width="300" src="https://firstcontributions.github.io/assets/Readme/copy-to-clipboard.png" alt="copy URL to clipboard" />
-
-**Clone** the repository to your machine. Go to the repository via your GitHub account and click on the **Code** button.
-
-Run the following command in your CLI/Terminal:
-
-```bash
-git clone https://github.com/YOUR_GITHUB_USRERNAME/git-proxy.git
-```
-
-<br />
-<br />
-
-#### Branch, code, commit and push
-
-<br />
-
-##### Branch
-
-You can start coding on the default branch on your fork of the project, commonly `master` or `main`. If you want to create a branch to clearly identify your work, run:
-
-```bash
-git checkout -b feature/name-of-the-feature-you-are-creating
-```
-
-<br />
-
-##### Code
-
-This part is up to you. Be creative and write some magical code! 🧙🪄
-
-<br />
-
-##### Commit
-
-Once you have finished making all of your improvements and changes, run the following:
-
-```bash
-git commit -m "YOUR COMMIT MESSAGE"
-```
-
-<br />
-
-##### Push
-
-Now that you've created a commit with your changes, it's time to push to GitHub:
-
-```bash
-git push
-```
-
-<br />
-
-##### Open a pull request
-
-With your changes applied to your fork of the project, it's time to [open a pull request from your repository](https://github.com/finos/git-proxy/compare)...
-
-<br />
+Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.
 
 ## Security
 
@@ -290,4 +96,3 @@ This project is distributed under the Apache-2.0 license. See <a href="./LICENSE
 ## Contact
 
 If you have a query or require support with this project, [raise an issue](https://github.com/finos/git-proxy/issues). Otherwise, reach out to [help@finos.org](mailto:help@finos.org).
-
diff --git a/config.schema.json b/config.schema.json
@@ -1,51 +1,48 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "https://json-schema.org/draft-07/schema",
   "$id": "https://git-proxy.finos.org/config.schema.json",
-  "title": "Git Proxy",
-  "description": "Configuration file for modifying the behaviour of git-proxy",
+  "title": "Git Proxy configuration file",
+  "description": "Configuration for customizing git-proxy",
   "type": "object",
-  "properties": {
-    "authorisedList": {
-      "description": "List of repositories that are authorised to be pushed to through the proxy.",
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/authorisedRepo"
-      }
-    },
-    "sink": {
-      "description": "List of database sources. The first source in the configuration with enabled=true will be used.",
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/database"
-      }
-    },
-    "authentication": {
-      "description": "List of authentication sources. The first source in the configuration with enabled=true will be used.",
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/authentication"
-      }
-    },
-    "tempPassword": {
-      "description": "Toggle the generation of temporary password for git-proxy admin user",
-      "type": "object",
+  "oneOf": [
+    {
       "properties": {
-        "sendEmail": { "type": "boolean" },
-        "emailConfig": {
-          "description": "Generic object to configure nodemailer. For full type information, please see https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/nodemailer",
-          "type": "object"
+        "authorisedList": {
+          "description": "List of repositories that are authorised to be pushed to through the proxy.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/authorisedRepo"
+          }
+        },
+        "sink": {
+          "description": "List of database sources. The first source in the configuration with enabled=true will be used.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/database"
+          }
+        },
+        "authentication": {
+          "description": "List of authentication sources. The first source in the configuration with enabled=true will be used.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/authentication"
+          }
+        },
+        "tempPassword": {
+          "description": "Toggle the generation of temporary password for git-proxy admin user",
+          "type": "object",
+          "properties": {
+            "sendEmail": { "type": "boolean" },
+            "emailConfig": {
+              "description": "Generic object to configure nodemailer. For full type information, please see https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/nodemailer",
+              "type": "object"
+            }
+          }
         }
       }
     }
-  },
-  "additionalProperties": false,
-  "anyOf": [
-    { "required": "authorisedList" },
-    { "required": "sink" },
-    { "required": "authentication" },
-    { "required": "tempPassword" }
   ],
-  "$defs": {
+  "definitions": {
     "authorisedRepo": {
       "type": "object",
       "properties": {
@@ -75,5 +72,6 @@
       },
       "required": [ "type", "enabled" ]
     }
-  }
+  },
+  "additionalProperties": false
 }
diff --git a/jsfh.config.json b/jsfh.config.json
@@ -0,0 +1,7 @@
+{
+  "template_name": "md_nested",
+  "show_toc": false,
+  "template_md_options": {
+    "show_array_restrictions": false
+  }
+}
diff --git a/package.json b/package.json
@@ -13,7 +13,8 @@
     "server-test": "mocha --exit",
     "test": "mocha --exit",
     "prepare": "node ./scripts/prepare.js",
-    "lint": "eslint --fix . --ext .js,.jsx"
+    "lint": "eslint --fix . --ext .js,.jsx",
+    "gen-schema-doc": "node ./scripts/doc-schema.js"
   },
   "bin": "./index.js",
   "author": "Paul Groves",