chore(backend): add getting started for the middleware and storage pr…

…oviders

docs/GettingStarted-Backend.md

@@ -0,0 +1,208 @@
+# Getting Started - Backend
+Dynamico backend has two parts:
+
+- [Server](#Server)
+- [Storage](#Storage)
+
+
+## Server
+
+### Initializing the middleware
+
+Dynamico backend service is powered by an express middleware that you can use along with any express server for both serving components and publishing components. However that's not necessarily a great production setup. Let's go over how you can implement a secure and reliable server for your dynamic components. It's easy, simple and quick! (and it's also fun!) 🙂
+
+Let's start with simply integrating it into a server
+
+<details>
+<summary>Creating an express server from scratch</summary>
+
+
+We're going to create a new node app. This app runs an express server that exposes dynamico endpoints. It'll require us to create and configure a storage provider. To learn more about how to properly set up storage for dynamico go to [Storage](#Storage).
+
+Let's start by creating a new node app and install all of the required dependencies. Open a terminal and run these commands:
+
+```bash
+$ mkdir dynamico-registry
+$ cd dynamico-registry
+$ npm init -y
+npm creates your node app with the name dynamico-registry
+$ npm install express @dynamico/express-middleware --save
+npm installation text
+$ touch index.js
+```
+
+Now open the folder in your favorite IDE. Open `index.js` and write this code in it:
+
+```javascript
+const express = require('express');
+const dynamico = require('@dynamico/express-middleware');
+
+const storageProvider = /*Initialize your storage provider*/
+const dynamicoMiddleware = dynamico(storageProvider);
+const app = express();
+app.use('/api/components', dynamicoMiddleware);
+app.listen(Number(process.env.PORT || 1234), () => {
+  console.log(`Listening on port ${process.env.PORT}`);
+});
+```
+
+Now you can jump to the [Storage](#Storage) section to initialize the storage provider of your choice.
+</details>
+
+<details>
+<summary>Integrate with an existing express server</summary>
+
+We're going to integrate the dynamico handlers with an existing express application so it will expose the dynamico endpoints. It'll require us to create and configure a storage provider. To learn more about how to properly set up storage for dynamico go to [Storage](#Storage).
+
+Let's start by adding the dependencies to your app:
+```bash
+$ npm install express @dynamico/express-middleware --save
+npm installation text
+```
+
+Open your project using your favorite IDE and find the appropriate place to add a new route. Usually it'll be next to files that contain lines like this:
+
+```javascript
+app.use('some/path', someHandler);
+```
+
+Open or create the file  and add this `require` statements to the file:
+```javascript
+const dynamico = require('@dynamico/express-middleware');
+```
+
+And create a handler and add a route to the app (this code assumes that you initialized an express router):
+
+```javascript
+const storageProvider = /*Initialize your storage provider*/
+
+const dynamicoMiddleware = dynamico(storageProvider);
+
+// Use the middleware
+```
+
+Now you can jump to the [Storage](#Storage) section to initialize the storage provider of your choice.
+</details>
+
+
+## Storage
+
+Dynamico backend uses the storage for saving and retrieving both components and an index of host apps that used it in the past (See [Architecture](Architecture)). Currently dynamico supports these storage types:
+
+<details>
+<summary>File system storage</summary>
+
+File system saves components in a specific folder provided in initialization. It uses node file system APIs and needs both read and write permissions as well as permissions to list the folder. Generally this isn't a production grade solution as it's not scalable and should be used mostly when playing around.
+
+Let's set up a file system storage provider. It'll take just a few minutes!
+
+Let's start by adding the dependency:
+```bash
+$ npm install @dynamico/fs-storage --save
+```
+
+Now find the file where you initialized dynamico middleware and add the following `require` statement.
+
+```javascript
+const { FSStorage } = require('@dynamico/fs-storage');
+```
+
+And initialize the provider and middleware:
+
+```javascript
+const storageProvider = new FSStorage('./components');
+const dynamicoMiddleware = dynamico(storageProvider);
+// Use the middleware
+```
+
+And that's it! you now have a server that uses file system to manage dynamic components.
+
+The full code looks something like this:
+
+```javascript
+const express = require('express');
+const dynamico = require('@dynamico/express-middleware');
+const { FSStorage } = require('@dynamico/fs-storage');
+
+const storageProvider = new FSStorage('./components');
+const dynamicoMiddleware = dynamico(storageProvider);
+
+const app = express();
+app.use('/api/components', dynamico(storageProvider);
+app.listen(Number(process.env.PORT || 1234), () => {
+  console.log(`Listening on port ${process.env.PORT}`);
+});
+```
+</details>
+<details>
+<summary>S3 Storage</summary>
+
+S3 storage hosts components in a specific bucket and expects to receive an initialized S3 client. It needs to have permissions for listing the objects in the bucket as well as read and write permissions. The write permission is required regardless of whether the server is set up to be read-only or not. The reason for this is that the server manages an index, which is saved as an object in the bucket. It uses the list permission to create the components versioning structure which is then used by the middleware when resolving the best component version. For more see [Architecture](Architecture). This guide assumes you followed the [Server](#Server) setup guide and you have an express app with dynamico middleware waiting for a storage provider.
+
+Let's set up an S3 storage provider, it won't take more than a few minutes!
+
+Start by installing the dependencies in your server:
+```bash
+$ npm install @dynamico/s3-storage aws-sdk --save
+```
+
+Now find the file where you initialized dynamico middleware and add the following `require` statements.
+
+```javascript
+const { S3Storage } = require('@dynamico/s3-storage');
+const { S3 } = require('aws-sdk');
+```
+
+And initialize the client and the provider as  well as the middleware:
+
+```javascript
+const s3Client = new S3({
+    credentials: {
+        accessKeyId: /*Your access key ID*/,
+        secretAccessKey: /*Your secret access key*/,
+        region: /*The region in which the bucket is defined*/
+    },
+    apiVersion: '2006-03-01'
+});
+const bucketName = 'dynamic-components';
+const storageProvider = new S3Storage({s3Client, bucketName});
+const dynamicoMiddleware = dynamico(storageProvider);
+// Use the middleware
+```
+
+And that's it! you now have a server that uses S3 storage to manage dynamic components.
+
+The full code looks something like this:
+
+```javascript
+const express = require('express');
+const dynamico = require('@dynamico/express-middleware');
+const { S3Storage } = require('@dynamico/s3-storage');
+const { S3 } = require('aws-sdk');
+
+const s3Client = new S3({
+    credentials: {
+        accessKeyId: /*Your access key ID*/,
+        secretAccessKey: /*Your secret access key*/,
+        region: /*The region in which the bucket is defined*/
+    },
+    apiVersion: '2006-03-01'
+});
+const bucketName = 'dynamic-components';
+const storageProvider = new S3Storage({s3Client, bucketName});
+
+const app = express();
+app.use('/api/components', dynamico(storageProvider);
+app.listen(Number(process.env.PORT || 1234), () => {
+  console.log(`Listening on port ${process.env.PORT}`);
+});
+```
+
+You can now test your code by running the server and opening a browser and in `http://localhost:1234/api/components/someComponent`
+
+The response should be 500 with an `InvalidVersionError`.
+</details>
+
+If the storage solution you use isn't listed here you can implement it yourself, it's fun! Reach out if you need help and don't forget to post a PR 😉.
+
+Now that you have a server that publishes components and serves them you can go over to the [Getting Started - Client](Getting_Started_-_Client) docs and run a real client with it.