Merge pull request #464 from Human-Connection/docs-improve_installation_instructions

Docs improve installation instructions

SUMMARY.md

@@ -4,12 +4,8 @@
 * [Edit this Documentation](edit-this-documentation.md)
 * [Installation](installation.md)
 * [Backend](backend/README.md)
-  * [graphql-with-apollo](backend/graphql-with-apollo/README.md)
-    * [GraphQL with Apollo](backend/graphql-with-apollo/graphql-with-apollo/README.md)
-      * [Mocking](backend/graphql-with-apollo/graphql-with-apollo/mocking.md)
-      * [Seeding](backend/graphql-with-apollo/graphql-with-apollo/seeding.md)
-  * [Import](backend/data-import.md)
-  * [Middleware](backend/middleware.md)
+  * [GraphQL](backend/graphql.md)
+  * [Legacy Migration](backend/db-migration-worker/README.md)
 * [Webapp](webapp/README.md)
   * [COMPONENTS](webapp/components.md)
   * [PLUGINS](webapp/plugins.md)

backend/README.md

@@ -1,137 +1,152 @@
 # Backend
 
+## Installation
+{% tabs %}
+{% tab title="Docker" %}
 
-## Installation with Docker
+Run the following command to install everything through docker.
 
-Make sure you are on a [node](https://nodejs.org/en/) version >= `v10.12.0`:
-
-```text
-  node --version
-```
-
-Run:
+The installation takes a bit longer on the first pass or on rebuild ...
 
 ```bash
-docker-compose up
+$ docker-compose up
 
-# create indices etc.
-docker-compose exec neo4j migrate
-
-# if you want seed data
-# open another terminal and run
-docker-compose exec backend yarn run db:seed
+# rebuild the containers for a cleanup
+$ docker-compose up --build
 ```
-
-App is [running on port 4000](http://localhost:4000/)
-
-To wipe out your neo4j database run:
+Open another terminal and create unique indices with:
 
 ```bash
-docker-compose down -v
+$ docker-compose exec neo4j migrate
 ```
 
-## Installation without Docker
+{% endtab %}
 
-Install dependencies:
+{% tab title="Without Docker" %}
+
+For the local installation you need a recent version of [node](https://nodejs.org/en/)
+(>= `v10.12.0`) and [Neo4J](https://neo4j.com/) along with
+[Apoc](https://github.com/neo4j-contrib/neo4j-apoc-procedures) plugin installed
+on your system.
 
 Download [Neo4j Community Edition](https://neo4j.com/download-center/#releases) and unpack the files.
 
 Download [Neo4j Apoc](https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases) and drop the file into the `plugins` folder of the just extracted Neo4j-Server
+Note that grand-stack-starter does not currently bundle a distribution of Neo4j. You can download [Neo4j Desktop](https://neo4j.com/download/) and run locally for development, spin up a [hosted Neo4j Sandbox instance](https://neo4j.com/download/), run Neo4j in one of the [many cloud options](https://neo4j.com/developer/guide-cloud-deployment/), [spin up Neo4j in a Docker container](https://neo4j.com/developer/docker/) or on Debian-based systems install [Neo4j from the Debian Repository](http://debian.neo4j.org/). Just be sure to update the Neo4j connection string and credentials accordingly in `.env`.
+Start Neo4J and confirm the database is running at [http://localhost:7474](http://localhost:7474).
 
-Start Neo4j
-
-```text
-neo4j\bin\neo4j start
+Now install node dependencies with [yarn](https://yarnpkg.com/en/):
+```bash
+$ cd backend
+$ yarn install
 ```
 
-and confirm it's running [here](http://localhost:7474)
+Copy Environment Variables:
+```bash
+# in backend/
+$ cp .env.template .env
+```
+
+Configure the new files according to your needs and your local setup.
+
+Create unique indices with:
 
 ```bash
-yarn install
-# -or-
-npm install
+$ ./neo4j/migrate.sh
 ```
 
-Copy:
-
-```text
-cp .env.template .env
-```
-
-Configure the file `.env` according to your needs and your local setup.
-
-Start the GraphQL service:
-
+Start the backend for development with:
 ```bash
-yarn dev
-# -or-
-npm dev
+$ yarn run dev
 ```
 
-And on the production machine run following:
-
+or start the backend in production environment with:
 ```bash
-yarn start
-# -or-
-npm start
+yarn run start
 ```
 
-This will start the GraphQL service \(by default on localhost:4000\) where you can issue GraphQL requests or access GraphQL Playground in the browser:
+{% endtab %}
+{% endtabs %}
+
+Your backend is up and running at [http://localhost:4000/](http://localhost:4000/)
+This will start the GraphQL service \(by default on localhost:4000\) where you can issue GraphQL requests or access GraphQL Playground in the browser. 
 
 ![GraphQL Playground](../.gitbook/assets/graphql-playground.png)
 
-## Configure
+You can access Neo4J through [http://localhost:7474/](http://localhost:7474/)
+for an interactive `cypher` shell and a visualization of the graph.
 
-Set your Neo4j connection string and credentials in `.env`. For example:
 
-_.env_
+#### Seed Database
 
-```yaml
-NEO4J_URI=bolt://localhost:7687
-NEO4J_USERNAME=neo4j
-NEO4J_PASSWORD=letmein
-```
+If you want your backend to return anything else than an empty response, you
+need to seed your database:
 
-> You need to install APOC as a plugin for the graph you create in the neo4j desktop app!
-
-Note that grand-stack-starter does not currently bundle a distribution of Neo4j. You can download [Neo4j Desktop](https://neo4j.com/download/) and run locally for development, spin up a [hosted Neo4j Sandbox instance](https://neo4j.com/download/), run Neo4j in one of the [many cloud options](https://neo4j.com/developer/guide-cloud-deployment/), [spin up Neo4j in a Docker container](https://neo4j.com/developer/docker/) or on Debian-based systems install [Neo4j from the Debian Repository](http://debian.neo4j.org/). Just be sure to update the Neo4j connection string and credentials accordingly in `.env`.
-
-# Seed and Reset the Database
-
-Optionally you can seed the GraphQL service by executing mutations that will write sample data to the database:
+{% tabs %}
+{% tab title="Docker" %}
 
+In another terminal run:
 ```bash
-yarn run db:seed
-# -or-
-npm run db:seed
+$ docker-compose exec backend yarn run db:seed
 ```
 
-For a reset you can use the reset script:
-
+To reset the database run:
 ```bash
-yarn db:reset
-# -or-
-npm run db:reset
+$ docker-compose exec backend yarn run db:reset
+# you could also wipe out your neo4j database and delete all volumes with:
+$ docker-compose down -v
 ```
+{% endtab %}
+
+{% tab title="Without Docker" %}
+Run:
+```bash
+$ yarn run db:seed
+```
+
+To reset the database run:
+```bash
+$ yarn run db:reset
+```
+{% endtab %}
+{% endtabs %}
+
 
 # Testing
 
 **Beware**: We have no multiple database setup at the moment. We clean the database after each test, running the tests will wipe out all your data!
 
+
+{% tabs %}
+{% tab title="Docker" %}
+
 Run the _**jest**_ tests:
 
 ```bash
-yarn run test
-# -or-
-npm run test
+$ docker-compose exec backend yarn run test:jest
 ```
 
 Run the _**cucumber**_ features:
 
 ```bash
-yarn run test:cucumber
-# -or-
-npm run test:cucumber
+$ docker-compose exec backend yarn run test:cucumber
 ```
 
-When some tests fail, try `yarn db:reset` and after that `yarn db:seed`. Then run the tests again
+{% endtab %}
+
+{% tab title="Without Docker" %}
+
+Run the _**jest**_ tests:
+
+```bash
+$ yarn run test:jest
+```
+
+Run the _**cucumber**_ features:
+
+```bash
+$ yarn run test:cucumber
+```
+
+{% endtab %}
+{% endtabs %}

backend/db-migration-worker/README.md

@@ -1,7 +1,9 @@
-# Import
+# Legacy Migration
 
 This guide helps you to import data from our legacy servers, which are using FeathersJS and MongoDB.
 
+**You can skip this if you don't plan to migrate any legacy applications!**
+
 ## Prerequisites
 
 You need [docker](https://www.docker.com/) installed on your machine. Furthermore you need SSH access to the server and you need to know the following login credentials and server settings:

backend/graphql-with-apollo/README.md

@@ -1,2 +0,0 @@
-# graphql-with-apollo
-

backend/graphql-with-apollo/graphql-with-apollo/README.md

@@ -1,6 +0,0 @@
-# GraphQL with Apollo
-
-GraphQL is a data query language which provides an alternative to REST and ad-hoc web service architectures. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server.
-
-![GraphQL Playground](../../../.gitbook/assets/graphql-playground%20%281%29.png)
-

backend/graphql-with-apollo/graphql-with-apollo/mocking.md

@@ -1,8 +0,0 @@
-# Mocking
-
-## Mocking API Results
-
-Alternatively you can just mock all responses from the api which let you build a frontend application without running a neo4j instance.
-
-Just set `MOCK=true` inside `.env` or pass it on application start.
-

backend/graphql-with-apollo/graphql-with-apollo/seeding.md

@@ -1,20 +0,0 @@
-# Seeding
-
-## Seeding The Database
-
-Optionally you can seed the GraphQL service by executing mutations that will write sample data to the database:
-
-{% tabs %}
-{% tab title="Yarn" %}
-```bash
-yarn db:seed
-```
-{% endtab %}
-
-{% tab title="NPM" %}
-```bash
-npm run db:seed
-```
-{% endtab %}
-{% endtabs %}
-

backend/graphql.md

@@ -1,8 +1,13 @@
-# Middleware
+# GraphQL with Apollo
+
+GraphQL is a data query language which provides an alternative to REST and ad-hoc web service architectures. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server.
+
+![GraphQL Playground](../../../.gitbook/assets/graphql-playground%20%281%29.png)
+
+## Middleware keeps resolvers clean
 
 ![](../.gitbook/assets/grafik-4.png)
 
-## Middleware keeps resolvers clean
 
 A well-organized codebase is key for the ability to maintain and easily introduce changes into an app. Figuring out the right structure for your code remains a continuous challenge - especially as an application grows and more developers are joining a project.
 
@@ -10,3 +15,4 @@ A common problem in GraphQL servers is that resolvers often get cluttered with b
 
 GraphQL Middleware uses the [_middleware pattern_](https://dzone.com/articles/understanding-middleware-pattern-in-expressjs) \(well-known from Express.js\) to pull out repetitive code from resolvers and execute it before or after one of your resolvers is invoked. This improves code modularity and keeps your resolvers clean and simple.
 
+

installation.md

@@ -1,41 +1,25 @@
 # Installation
 
-## General Install Instructions
-
 The repository can be found on GitHub. [https://github.com/Human-Connection/Human-Connection](https://github.com/Human-Connection/Human-Connection)
 
-{% hint style="info" %}
-TODO: Create documentation section for How to Start and Beginners.
-{% endhint %}
+We give write permissions to every developer who asks for it. Just text us on
+[Discord](https://discord.gg/6ub73U3).
 
-Here are some general informations about our [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
+## Clone the Repository
 
-#### Fork the Repository
 
-Click on the fork button.
-
-![Fork screenshot](.gitbook/assets/screenshot-forking-nitro.png)
-
-#### Clone your new Repository
-
-Set the current working folder to the path in which the repository should be cloned \(copied\).
-
-```bash
-$ cd PATH-FOR-REPO
-```
-
-For cloning your new repository to your local machine modify the following command to add your GitHub user name.
+Clone the repository, this will create a new folder called `Human-Connection`:
 
 {% tabs %}
 {% tab title="HTTPS" %}
 ```bash
-$ git clone https://github.com/YOUR-GITHUB-USERNAME/Human-Connection.git
+$ git clone https://github.com/Human-Connection/Human-Connection.git
 ```
 {% endtab %}
 
 {% tab title="SSH" %}
 ```bash
-$ git clone git@github.com:YOUR-GITHUB-USERNAME/Human-Connection.git
+$ git clone git@github.com:Human-Connection/Human-Connection.git
 ```
 {% endtab %}
 {% endtabs %}
@@ -46,21 +30,21 @@ Change into the new folder.
 $ cd Human-Connection
 ```
 
-Add the original Human Connection repository as `upstream`. This prepares you to synchronize your local clone with a simple pull command in the future.
+## Directory Layout
 
-{% tabs %}
-{% tab title="HTTPS" %}
-```bash
-$ git remote add upstream https://github.com/Human-Connection/Human-Connection.git
-```
-{% endtab %}
+There are four important directories:
+* [Backend](./backend) runs on the server and is a middleware between database and frontend
+* [Frontend](./webapp) is a server-side-rendered and client-side-rendered web frontend
+* [Deployment](./deployment) configuration for kubernetes
+* [Cypress](./cypress) contains end-to-end tests and executable feature specifications
 
-{% tab title="SSH" %}
-```bash
-$ git remote add upstream git@github.com:Human-Connection/Human-Connection.git
-```
-{% endtab %}
-{% endtabs %}
+In order to setup the application and start to develop features you have to
+setup **frontend** and **backend**.
+
+There are two approaches:
+
+1. Local installation, which means you have to take care of dependencies yourself
+2. **Or** Install everything through docker which takes care of dependencies for you
 
 ## Docker Installation
 
@@ -95,72 +79,4 @@ $ docker-compose --version
 docker-compose version 1.23.2
 ```
 
-### Install Nitro with Docker
-
-Run the following command to install Nitro as a Docker container. This installation includes Neo4j.
-
-The installation takes a bit longer on the first pass or on rebuild ...
-
-```bash
-$ docker-compose up
-
-# rebuild the containers for a cleanup
-$ docker-compose up --build
-```
-
-#### Seed Neo4j in Docker
-
-To seed the Neo4j database with default data, that GraphQL requests or playing with our GraphQL Playground returns anything else than an empty response, run the command.
-
-Run the following command to seed the Neo4j database with default data requested by Nitro-Web through GraphQL or when you play with our GraphQL playground.
-
-```bash
-# open another terminal
-
-# create indices etc.
-$ docker-compose exec neo4j migrate
-
-# seed database
-$ docker-compose exec backend yarn run db:seed
-```
-
-**Wipe out Neo4j database in Docker**
-
-To wipe out your neo4j database and delete the volumes send command:
-
-```bash
-# open another terminal and run
-$ docker-compose down -v
-```
-
-**Video Tutorial**
-
-{% hint style="info" %}
-TODO: Link to video
-{% endhint %}
-
-#### Development with Kubernetes
-
-For further informations see also our [Kubernetes documentation](https://github.com/Human-Connection/Human-Connection/tree/9bede1913b829a5c2916fc206c1fe4c83c49a4bc/kubernetes.md).
-
-## Local Installation
-
-#### Install the dependencies
-
-```bash
-$ yarn install
-$ cd backend && yarn install
-$ cd ../webapp && yarn install
-$ cd ..
-```
-
-#### Copy Environment Variables
-
-```bash
-$ cp cypress.env.template.json cypress.env.json
-$ cp backend/.env.template backend/.env
-$ cp webapp/.env.template webapp/.env
-```
-
-Configure the new files according to your needs and your local setup.