feat: runnable exec + CLI args via yargs + install docs

- add "bin" to package.json to support running git-proxy as an
  executable. Largely taken from #184 and fixes #183
- added --config and --validate command line flags via yargs. These will
  allow custom user configurations with a default behaviour of loading
  from the current working dir and/or default settings. --validate uses
  JSON Schema to validate the config.
- update docs to reflect new CLI args and additional details of running
  the app via npx
- load default settings from a module instead of explicit file path
- add test for default & user setting merging
- bump @finos/git-proxy to 1.1.0
- Remove old X.509 certificate and private key, which I assume was
  included previously to run git-proxy with TLS enabled via a demo. Can
  be re-added as needed but probably shouldn't be included in src (even
  if its for demo only).

README.md

@@ -45,16 +45,46 @@ Git Proxy is built with a developer-first mindset. By presenting simple-to-follo
 
 ## Installation
 
-To install Git Proxy, use the [npm](https://www.npmjs.com/) package manager:
+To install Git Proxy, you must have [Node.js 16 or later](https://nodejs.org/en/download) installed. Use [npm](https://www.npmjs.com) to install the package:
 
 ```bash
-$ npm install @finos/git-proxy
+$ npm install -g @finos/git-proxy
 ```
 
 To install a specific version of Git Proxy, append the version to the end of the `install` command:
 
 ```bash
-$ npm install @finos/[email protected]
+$ npm install -g @finos/[email protected]
+```
+
+To start the server, run `git-proxy`. Alternatively, you can also install & run git-proxy directly using `npx`:
+
+```bash
+$ git-proxy
+# Running with npx - if the package isn't already installed, npx will prompt you to confirm installation
+$ npx --package=@finos/[email protected] -- git-proxy
+```
+
+## Configuration
+By default, git-proxy ships with a [default configuration](./proxy.config.json) for demonstration purposes. In most environments, this should be overridden by your user-specific values.
+
+To set your own values, create a `proxy.config.json` in the current working directory. This will be loaded when you execute `git-proxy` if present.
+
+If you wish to specify a different file location to use as configuration, use the `-c/--config` command-line argument:
+
+```bash
+$ git-proxy --config /etc/gitproxy/config.json
+# With npx
+$ npx -- @finos/git-proxy --config /etc/gitproxy/config.json
+```
+
+### Validation
+To validate your configuration against the [included schema](config.schema.json), use the following included script:
+
+```bash
+$ git-proxy --validate
+# Run validation against a configuration at a custom file location
+$ git-proxy --validate --config /etc/gitproxy/config.json
 ```
 
 ## Contributing

config.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git-proxy.finos.org/config.schema.json",
+  "title": "Git Proxy",
+  "description": "Configuration file for modifying the behaviour of 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",
+      "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": {
+    "authorisedRepo": {
+      "type": "object",
+      "properties": {
+        "project": { "type": "string" },
+        "name": { "type": "string" },
+        "url": { "type": "string" }
+      },
+      "required": [ "project", "name", "url" ]
+    },
+    "database": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "enabled": { "type": "boolean" },
+        "connectionString": { "type": "string" },
+        "options": { "type": "object" },
+        "params": { "type": "object" }
+      },
+      "required": [ "type", "enabled" ]
+    },
+    "authentication": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "enabled": { "type": "boolean" },
+        "options": { "type": "object" }
+      },
+      "required": [ "type", "enabled" ]
+    }
+  }
+}

index.js

@@ -1,3 +1,48 @@
+#!/usr/bin/env node
+/* eslint-disable max-len */
+const argv = require('yargs/yargs')(process.argv.slice(2))
+  .usage('Usage: $0 [options]')
+  .options({
+    validate: {
+      description:
+        'Check the proxy.config.json file in the current working directory for validation errors.',
+      required: false,
+      alias: 'v',
+    },
+    config: {
+      description: 'Path to custom git-proxy configuration file.',
+      default: 'proxy.config.json',
+      required: false,
+      alias: 'c',
+    },
+  }).argv;
+
+require('./src/config/file').configFile = argv.c ? argv.c : undefined;
+
+if (argv.v) {
+  const fs = require('fs');
+  const path = require('path');
+  const validate = require('jsonschema').validate;
+  const configFile = require('./src/config/file').configFile;
+
+  if (!fs.existsSync(configFile)) {
+    console.error(
+      `Config file ${configFile} doesn't exist, nothing to validate! Did you forget -c/--config?`,
+    );
+    process.exit(1);
+  }
+
+  const config = JSON.parse(fs.readFileSync(configFile));
+  const schema = JSON.parse(
+    fs.readFileSync(path.join(__dirname, 'config.schema.json')),
+  );
+
+  validate(config, schema, { required: true, throwError: true });
+
+  console.log(`${configFile} is valid`);
+  process.exit(0);
+}
+
 const proxy = require('./src/proxy');
 const service = require('./src/service');
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finos/git-proxy",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Deploy custom push protections and policies on top of Git.",
   "scripts": {
     "client": "vite --config vite.config.js",
@@ -15,6 +15,7 @@
     "prepare": "node ./scripts/prepare.js",
     "lint": "eslint --fix . --ext .js,.jsx"
   },
+  "bin": "./index.js",
   "author": "Paul Groves",
   "license": "Apache-2.0",
   "dependencies": {
@@ -37,6 +38,7 @@
     "generate-password": "^1.5.1",
     "history": "5.3.0",
     "load-plugin": "^5.1.0",
+    "jsonschema": "^1.4.1",
     "lodash": "^4.17.21",
     "moment": "^2.29.4",
     "mongodb": "^5.0.0",
@@ -51,7 +53,8 @@
     "react-dom": "^16.13.1",
     "react-html-parser": "^2.0.2",
     "react-router-dom": "6.16.0",
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.0",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.22.9",

src/config/file.js

@@ -0,0 +1,14 @@
+const path = require('path');
+// eslint-disable-next-line prefer-const
+let configFile = undefined;
+
+module.exports = {
+  get configFile() {
+    return configFile
+      ? configFile
+      : path.join(process.cwd(), 'proxy.config.json');
+  },
+  set configFile(file) {
+    configFile = file;
+  },
+};