diff --git a/.gitbook/assets/screenshot-forking-nitro-backend.png b/.gitbook/assets/screenshot-forking-nitro-backend.png new file mode 100644 index 000000000..6d52dd130 Binary files /dev/null and b/.gitbook/assets/screenshot-forking-nitro-backend.png differ diff --git a/.gitbook/assets/screenshot-neo4j-download-center-current-releases.png b/.gitbook/assets/screenshot-neo4j-download-center-current-releases.png new file mode 100644 index 000000000..8d9033864 Binary files /dev/null and b/.gitbook/assets/screenshot-neo4j-download-center-current-releases.png differ diff --git a/SUMMARY.md b/SUMMARY.md index cd5d36a2d..cae0fac60 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,7 +5,7 @@ ## Backend * [Backend Installation](backend/installation/README.md) - * [Configuration](backend/installation/configuration.md) + * [Neo4j Installation and Configuration](backend/installation/configuration.md) * [Docker](backend/installation/docker.md) * [GraphQL with Apollo](backend/graphql-with-apollo/README.md) * [Mocking](backend/graphql-with-apollo/mocking.md) diff --git a/backend/installation/README.md b/backend/installation/README.md index dea885602..bdd7383a5 100644 --- a/backend/installation/README.md +++ b/backend/installation/README.md @@ -1,31 +1,59 @@ # Backend Installation -{% hint style="warning" %} -This documentation should be split into a **local** and a **docker** installation variant. Also maybe there should be a main docker installation guide for the whole system at once!? -{% endhint %} -### Clone Repository - -The Backend Repository can be found on github. +The Backend repository can be found on GitHub. [https://github.com/Human-Connection/Nitro-Backend](https://github.com/Human-Connection/Nitro-Backend) -## Fork the repo +{% hint style="info" %} TODO: Create documentation section for How to Start and Beginners. {% endhint %} + +Here are some general informations about our [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962). + +### Fork the Repository Click on the fork button. -![Fork screenshot](https://i.imgur.com/syoN9rF.png) +![Fork screenshot](../../.gitbook/assets/screenshot-forking-nitro-backend.png) -After you have forked, modify the following command to add your Github user name. +### Clone your new Repository + +Set the current working folder to the path in which the backend repository should be cloned (copied). + +```bash +$ cd PATH-FOR-NITRO-BACKEND +``` + +For cloning your new repository to your local machine modify the following command to add your GitHub user name. {% tabs %} {% tab title="HTTPS" %} ```bash -git clone https://github.com/YOUR-GITHUB-USERNAME/Nitro-Backend.git +$ git clone https://github.com/YOUR-GITHUB-USERNAME/Nitro-Backend.git ``` {% endtab %} {% tab title="SSH" %} ```bash -git clone git@github.com:YOUR-GITHUB-USERNAME/Nitro-Backend.git +$ git clone git@github.com:YOUR-GITHUB-USERNAME/Nitro-Backend.git +``` +{% endtab %} +{% endtabs %} + +Change into the new folder. + +```bash +$ cd Nitro-Backend +``` + +Add the original Human Connection repository as `upstream`. This prepares you to synchronize your local clone with a simple pull command in the future. + +{% tabs %} +{% tab title="HTTPS" %} +```bash +$ git remote add upstream https://github.com/Human-Connection/Nitro-Backend.git +``` +{% endtab %} +{% tab title="SSH" %} +```bash +$ git remote add upstream git@github.com:Human-Connection/Nitro-Backend.git ``` {% endtab %} {% endtabs %} @@ -33,23 +61,47 @@ git clone git@github.com:YOUR-GITHUB-USERNAME/Nitro-Backend.git ### Copy Environment Variables ```bash -cp .env.template .env +$ cp .env.template .env ``` Configure the file `.env` according to your needs and your local setup. + +## Installation and Usage with Docker + +{% hint style="info" %} +TODO: How to install Docker for Human Connection … +(Also maybe there should be a main docker installation guide for the whole system at once!?) +{% endhint %} + +For further informations see also our [Docker documentation](docker.md). + + +## Local Installation + +Make sure that you have a recent version of [yarn](https://yarnpkg.com/en/) or [npm](https://www.npmjs.com) installed before you proceed. E.g. we have the following versions: + +```sh +$ yarn --version +1.12.3 +$ npm --version +6.4.1 +``` + +If the `yarn` or `npm` command is unknown you may use the [docker installation](#installation-and-usage-with-docker) (see above) or contact the developer team at [Discord](https://discord.gg/6ub73U3) if you have any questions: + ### Install Dependencies {% tabs %} {% tab title="Yarn" %} ```bash -yarn install +$ yarn install ``` {% endtab %} {% tab title="NPM" %} ```bash -npm install +$ npm install ``` {% endtab %} {% endtabs %} @@ -61,16 +113,16 @@ npm install #### Development ```bash -yarn run dev +$ yarn run dev ``` #### Production ```bash # you will need to build the app first (done while building the docker image) -yarn run build +$ yarn run build # run after build (dist folder must exist) -yarn run start +$ yarn run start ``` {% endtab %} @@ -78,19 +130,22 @@ yarn run start #### Development ```bash -npm run dev +$ npm run dev ``` #### Production ```bash # you will need to build the app first (done while building the docker image) -npm run build +$ npm run build # run after build (dist folder must exist) -npm run start +$ npm run start ``` {% endtab %} {% endtabs %} -This will start the GraphQL service \(by default on [http://localhost:4000](http://localhost:4000)\) where you can issue GraphQL requests or access GraphQL Playground in the browser +This will start the GraphQL service \(by default on [http://localhost:4000](http://localhost:4000)\) where you can issue GraphQL requests or access GraphQL Playground in the browser. +{% hint style="warning" %} +But before you can issue GraphQL requests or access GraphQL Playground you have to install, start and seed your Neo4j database. See next step … +{% endhint %} diff --git a/backend/installation/configuration.md b/backend/installation/configuration.md index 82d048f5a..aea5ca51b 100644 --- a/backend/installation/configuration.md +++ b/backend/installation/configuration.md @@ -1,6 +1,7 @@ -# Configuration +# Neo4j Installation and Configuration -### Configure + +## Configure Enviroment Set your Neo4j connection string and credentials in `.env`. For example: @@ -14,17 +15,83 @@ NEO4J_PASSWORD=letmein {% endcode-tabs-item %} {% endcode-tabs %} + +## Neo4j Installation + {% hint style="warning" %} -You **need to install APOC** as a plugin for the graph you create in the neo4j desktop app! +You **need to install APOC** as a plugin for the graph you create in neo4j! {% endhint %} -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`. +Note that grand-stack-starter does not currently bundle a distribution of Neo4j. +Now there are a lot alternatives how to install Neo4J. + +{% tabs %} + +{% tab title="Neo4j Desktop" %} + +You can [download Neo4j Desktop](https://neo4j.com/download-center/) run locally for development. +Choose tab **Neo4j Desktop**. + +![Neo4j Download-Center screenshot](../../.gitbook/assets/screenshot-neo4j-download-center-current-releases.png) + +After the download is done install the Neo4j Desktop application and open it. +E.g. we have the following version: + +``` +Neo4j Desktop 1.1.13 +``` + +Click on the empty project **My Project** to choose it. + +Click in the **Add Graph** area and after two buttons appear in it click on **Create a Local Graph**. + +Optionally, set the name of the new Graph for clarity to **Human Connection DB**. +Set the password to **letmein** which is our default password of our `.env.template`. You can choose another password and later change your connection settings, too. Then click on **Create** and the database will be generated. + +After generation of the database was successful, please click in the **Add Plugin** area. +Then click the **Install** button of the **APOC** area. +Now an additional **Install** button appears and you click on it again. If the **APOC-Plugin** is installed by now close the **Plugins** window. + +In the **Human Connection DB** area is a **Manage** button. By clicking it the area switches into a manage area with a lot of information and setting possibilities. + +Start the Graph database by clicking the **Play-Symbol** button. +In the **Logs** tab you'll find the status of the start up. + +If you have a look in the **Details** tab you find the connection info. The bolt port should be `7687` as we set it for our [environment configuration](#configure-environment) above. + +{% endtab %} + +{% tab title="Neo4j Non-Desktop Alternatives" %} + +You can spin up a [hosted Neo4j Sandbox instance](https://neo4j.com/download-center/), 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 credentials in `.env`. **Install APOC plugin on Debian-based systems** -When you have install Neo4j from the Debian Repository, then download the [APOC plugin](https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/3.5.0.1/apoc-3.5.0.1-all.jar) to the `/var/lib/neo4j/plugins` directory manually or with: +Install `neo4j` from the Debian Repository, then [download the APOC plugin](https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/3.4.0.3/apoc-3.4.0.3-all.jar) to the `/var/lib/neo4j/plugins` directory, e.g. with: ```text wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/3.5.0.1/apoc-3.5.0.1-all.jar -P /var/lib/neo4j/plugins ``` +{% endtab %} + +{% endtabs %} + + +## Seeding Database with Data + +Now we have to seed our database with default data, so that GraphQL requests or playing with our GraphQL Playground returns anything else than an empty response. + +To fill the database with some seed data, run the following command in your terminal: +```bash +$ yarn run db:seed +``` + +To wipe out the database: +```bash +$ yarn run db:reset +``` + +Now your backend is ready for requests. You can click on the **Open Browser** button in Neo4j Desktop to check if the seeding was successful or open [http://localhost:7474/](http://localhost:7474/) in your browser. + +Click the **Data-Symbol** at the left upper corner and then click on the **Node Label** + **User** to see a graph of the user relations, as an example.