feat(docs): Add configuration guide

Closes #346

docs/content/article/roadmap.md

@@ -9,7 +9,6 @@ showtoc: false
 Here is a list of some of the main outstanding tasks that are planned for the v1.0 release, at which point Vendure will come out of beta:
 
 * Complete the Channels implementation
-* Customer groups
 * Back order handling
 * Administrator creation & editing of orders
 * Custom authentication support

docs/content/docs/developer-guide/configuration.md

@@ -0,0 +1,172 @@
+---
+title: "Configuration"
+showtoc: true
+---
+
+# Configuration
+
+Every aspect of the Vendure server is configured via a single, central `VendureConfig` object. This object is passed into the [`bootstrap`]({{< relref "bootstrap" >}}) and [`bootstrapWorker`]({{< relref "bootstrap-worker" >}}) functions to start up the Vendure server and worker respectively.
+
+The `VendureConfig` object is organised into sections, grouping related settings together. For example, [`VendureConfig.apiOptions`]({{< relref "api-options" >}}) contains all the config for the GraphQL APIs, whereas [`VendureConfig.authOptions`]({{< relref "auth-options" >}}) deals with authentication.
+
+## Working with the VendureConfig object
+
+Since the VendureConfig is just a JavaScript object, it can be managed and manipulated according to your needs. For example:
+
+### Using environment variables
+
+Environment variables can be used when you don't want to hard-code certain values which may change, e.g. depending on whether running locally, in staging or in production:
+
+```TypeScript
+export const config: VendureConfig = {
+  apiOptions: {
+    hostname: process.env.HOSTNAME,
+    port: process.env.PORT,
+  }
+  // ...
+};
+```
+
+They are also useful so that sensitive credentials do not need to be hard-coded and committed to source control:
+
+```TypeScript
+export const config: VendureConfig = {
+  dbConnectionOptions: {
+    type: 'postgres',
+    username: process.env.DB_USERNAME,
+    password: process.env.DB_PASSWORD,
+    database: 'vendure',
+  },
+  // ...
+}
+```
+
+### Splitting config across files
+
+If the config object grows too large, you can split it across several files. For example, the `plugins` array in a real-world project can easily grow quite big:
+
+```TypeScript
+// vendure-config-plugins.ts
+
+export const plugins: VendureConfig['plugins'] = [
+  CustomPlugin,
+  AssetServerPlugin.init({
+      route: 'assets',
+      assetUploadDir: path.join(__dirname, 'assets'),
+      port: 5002,
+  }),
+  DefaultJobQueuePlugin,
+  ElasticsearchPlugin.init({
+      host: 'localhost',
+      port: 9200,
+  }),
+  EmailPlugin.init({
+    // ...lots of lines of config
+  }),
+];
+```
+
+```TypeScript
+// vendure-config.ts
+
+import { plugins } from 'vendure-config-plugins';
+
+export const config: VendureConfig = {
+  plugins,
+  // ...
+}
+```
+
+## Important Configuration Settings
+
+In this guide we will take a look at those configuration options needed for getting the server up-and-running.
+
+{{< alert "primary" >}}
+A description of every available configuration option can be found in the [VendureConfig API documentation]({{< relref "vendure-config" >}}).
+{{< /alert >}}
+
+### Specifying API hostname & port etc
+
+The [`VendureConfig.apiOptions`]({{< relref "api-options" >}}) object is used to set the hostname, port, as well as other API-related concerns. Express middleware and Apollo Server plugins may also be specified here.
+
+Example:
+
+```TypeScript
+export const config: VendureConfig = {
+  apiOptions: {
+    hostname: 'localhost',
+    port: 3000,
+    adminApiPath: '/admin',
+    shopApiPath: '/shop',
+    middleware: [{
+      // add some Express middleware to the Shop API route
+      handler: timeout('5s'),
+      route: 'shop',
+    }]
+  },
+  // ...
+}
+```
+
+### Connecting to the database
+
+The database connection is configured with the `VendureConfig.dbConnectionOptions` object. This object is actually the [TypeORM configuration object](https://typeorm.io/#/connection-options) and is passed directly to TypeORM.
+
+Example:
+
+```TypeScript
+export const config: VendureConfig = {
+  dbConnectionOptions: {
+    type: 'postgres',
+    host: process.env.DB_HOST,
+    port: process.env.DB_PORT,
+    synchronize: false,
+    username: process.env.DB_USERNAME,
+    password: process.env.DB_PASSWORD,
+    database: 'vendure',
+    migrations: [path.join(__dirname, 'migrations/*.ts')],
+  },
+  // ...
+}
+```
+
+### Configuring authentication
+
+Authentication settings are configured with [`VendureConfig.authOptions`]({{< relref "auth-options" >}}). The most important setting here is whether the storefront client will use cookies or bearer tokens to manage user sessions. For more detail on this topic, see [the Authentication & Sessions guide]({{< relref "authentication-and-sessions" >}}).
+
+The username and default password of the superadmin user can also be specified here. In production, it is advisable to use environment variables for these settings.
+
+Example:
+
+```TypeScript
+export const config: VendureConfig = {
+  authOptions: {
+    tokenMethod: 'cookie',
+    sessionSecret: process.env.COOKIE_SESSION_SECRET,
+    requireVerification: true,
+    superadminCredentials: {
+      identifier: process.env.SUPERADMIN_USERNAME,
+      password: process.env.SUPERADMIN_PASSWORD,
+    },
+  },
+  // ...
+}
+```
+
+### Connecting to the worker
+
+The Vendure worker is configured with [`VendureConfig.workerOptions`]({{< relref "worker-options" >}}). The worker is a [Nestjs microservice](https://docs.nestjs.com/microservices/basics) which runs in another process (and can be located on another server or in another container) from the main server.
+
+By default, the worker communication happens over TCP. If you want to run the worker in a separate container or physical server to the server, please see the [deployment guide]({{< relref "deployment" >}}#deploying-the-worker).
+
+```TypeScript
+export const config: VendureConfig = {
+  workerOptions: {
+    options: {
+      host: 'localhost',
+      port: 3020,
+    },
+  },
+  // ...
+}
+```

docs/content/docs/developer-guide/deployment.md

@@ -48,6 +48,55 @@ REQUEST: GET http://localhost:3000/health
 
 Health checks are built on the [Nestjs Terminus module](https://docs.nestjs.com/recipes/terminus). You can also add your own health checks by creating plugins that make use of the [HealthCheckRegistryService]({{< relref "health-check-registry-service" >}}).
 
+## Deploying the worker
+
+By default the worker and server communicate over TCP (other protocols can be used - see the [Nestjs microservices docs](https://docs.nestjs.com/microservices/basics)). In production, you may wish to run the worker in a separate container or machine than the Vendure server. In this case, the `VendureConfig.workerOptions` that get passed to `bootstrap()` and `bootstrapWorker()` will need to be different:
+
+#### Example Scenario
+
+* The Vendure server and worker will run on separate web servers (or in separate containers)
+* These servers are behind a reverse proxy, e.g. nginx
+* Only the Vendure server machine should be accessible from the internet - nginx is configured to forward requests to port 443 (https traffic) to the Vendure server which is listening on port 3000.
+
+```TypeScript
+// vendure-config.ts
+
+export const config: VendureConfig = {
+  apiOptions: {
+      hostname: 'localhost',
+      port: 3000,
+  },
+  workerOptions: {
+    options: {
+      host: '<IP address of the worker server>',
+      port: 3020,
+    },
+  },
+  // ...
+}
+```
+
+```TypeScript
+// index.ts
+
+bootstrap(config);
+```
+
+```TypeScript
+// index-worker.ts
+
+const workerConfig = {
+  ...config,
+  workerOptions: {
+    options: {
+      host: 'localhost',
+      port: 3020,
+    },
+  },
+};
+bootstrapWorker(workerConfig);
+```
+
 ## Admin UI
 
 If you have customized the Admin UI with extensions, it can make sense to [compile your extensions ahead-of-time as part of the deployment process]({{< relref "/docs/plugins/extending-the-admin-ui" >}}#compiling-as-a-deployment-step).

docs/content/docs/developer-guide/vendure-worker.md

@@ -35,7 +35,7 @@ Internally, the Worker is an instance of a [NestJS microservice](https://docs.ne
 
 ## Running on the main process
 
-There is an option `runInMainProcess` which, if set to `true` will cause the Worker to be bootstrapped along with the main application, without the need for a separate process running `bootstrapWorker`. This is mainly used for testing and development, and is not advised for production use, since it negates the benefits of running long tasks off of the main process.
+There is an option `runInMainProcess` which, if set to `true` will cause the Worker to be bootstrapped along with the main application, without the need for a separate process running `bootstrapWorker`. This is mainly used for testing and automated tasks, and is not advised for production use, since it negates the benefits of running long tasks off of the main process.
 
 ## Running custom code on the worker
 

docs/content/docs/getting-started.md

@@ -72,5 +72,6 @@ Log in with the superadmin credentials:
 
 ## Next Steps
 
+* Learn more about [Configuration]({{< relref "/docs/developer-guide/configuration" >}}) of your Vendure server.
 * Get a better understanding of how Vendure works by reading the [Architecture Overview]({{< relref "/docs/developer-guide/overview" >}})
 * Learn how to implement a storefront with the [GraphQL API Guide]({{< relref "/docs/storefront/shop-api-guide" >}})

docs/content/docs/plugins/available-plugins.md

@@ -16,5 +16,7 @@ The Vendure monorepo contains a number of "core" plugins - that is, commonly-use
 
 ## Third-party plugins
 
-Have you created a Vendure plugin that you'd like to share? Contact us and we can list it here!
+Have you created a Vendure plugin that you'd like to share? Contact us and we can list it here! 
+
+For now, you'll find some community plugins in [these GitHub search results](https://github.com/search?q=vendure+-user%3Avendure-ecommerce&type=Repositories).
  

packages/core/src/config/vendure-config.ts

@@ -595,6 +595,8 @@ export interface VendureConfig {
     /**
      * @description
      * The connection options used by TypeORM to connect to the database.
+     * See the [TypeORM documentation](https://typeorm.io/#/connection-options) for a
+     * full description of all available options.
      */
     dbConnectionOptions: ConnectionOptions;
     /**