diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..196b96fff --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Apple macOS folder attribute file +.DS_Store diff --git a/SUMMARY.md b/SUMMARY.md index cae0fac60..d6d8e4e6c 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,8 +5,9 @@ ## Backend * [Backend Installation](backend/installation/README.md) - * [Neo4j Installation and Configuration](backend/installation/configuration.md) - * [Docker](backend/installation/docker.md) + * [Docker Installation](backend/installation/docker-backend.md) + * [Local Installation](backend/installation/local-backend.md) + * [Kubernetes](backend/installation/kubernetes.md) * [GraphQL with Apollo](backend/graphql-with-apollo/README.md) * [Mocking](backend/graphql-with-apollo/mocking.md) * [Seeding](backend/graphql-with-apollo/seeding.md) @@ -26,7 +27,8 @@ * [Integration Testing](workflow/testing/integration-testing.md) * [Component Testing](workflow/testing/component-testing.md) * [Unit Testing](workflow/testing/unit-testing.md) -* [Contribute](workflow/pull-requests.md) +* [Contribute](workflow/README.md) + * [Our GitHub Workflow](workflow/contribute/github-workflow.md) * [Deployment](workflow/deployment.md) ## Documentation diff --git a/backend/installation/README.md b/backend/installation/README.md index 040c1c22d..af7dfbfff 100644 --- a/backend/installation/README.md +++ b/backend/installation/README.md @@ -26,15 +26,19 @@ For cloning your new repository to your local machine modify the following comma {% tabs %} {% tab title="HTTPS" %} + ```bash $ 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 ``` + {% endtab %} {% endtabs %} @@ -48,15 +52,19 @@ Add the original Human Connection repository as `upstream`. This prepares you to {% 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 %} @@ -67,85 +75,3 @@ $ 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: - -```bash -$ 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 -``` -{% endtab %} - -{% tab title="NPM" %} -```bash -$ npm install -``` -{% endtab %} -{% endtabs %} - -### Start the Server - -{% tabs %} -{% tab title="Yarn" %} -#### Development - -```bash -$ yarn run dev -``` - -#### Production - -```bash -# you will need to build the app first (done while building the docker image) -$ yarn run build -# run after build (dist folder must exist) -$ yarn run start -``` -{% endtab %} - -{% tab title="NPM" %} -#### Development - -```bash -$ npm run dev -``` - -#### Production - -```bash -# you will need to build the app first (done while building the docker image) -$ npm run build -# run after build (dist folder must exist) -$ 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. - -{% 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/docker-backend.md b/backend/installation/docker-backend.md new file mode 100644 index 000000000..18b88ce98 --- /dev/null +++ b/backend/installation/docker-backend.md @@ -0,0 +1,82 @@ +# Docker Installation + +Docker is a software development container tool that combines software and its dependencies into one standardized unit that contains everything needed to run it. This helps us to avoid problems with dependencies and makes installation easier. + +## General Installation of Docker + +There are [sevaral ways to install Docker CE](https://docs.docker.com/install/) on your computer or server. + +{% tabs %} +{% tab title="Docker Desktop macOS" %} + +Follow these instructions to [install Docker Desktop on macOS](https://docs.docker.com/docker-for-mac/install/). + +{% endtab %} +{% tab title="Docker Desktop Windows" %} + +Follow these instructions to [install Docker Desktop on Windows](https://docs.docker.com/docker-for-windows/install/). + +{% endtab %} +{% tab title="Docker CE" %} + +Follow these instructions to [install Docker CE](https://docs.docker.com/install/). + +{% endtab %} +{% endtabs %} + +Check the correct Docker installation by checking the version before proceeding. E.g. we have the following versions: + +```bash +$ docker --version +Docker version 18.09.2 +$ docker-compose --version +docker-compose version 1.23.2 +``` + +## Install Nitro-BackEnd with Docker + +Run the following command to install Nitro-Backend 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](kubernetes.md). diff --git a/backend/installation/docker.md b/backend/installation/docker.md deleted file mode 100644 index 9892302a6..000000000 --- a/backend/installation/docker.md +++ /dev/null @@ -1,5 +0,0 @@ -# Docker - -Currently you can find some documentation here: -[https://github.com/Human-Connection/Nitro-Backend/tree/master/kubernetes](https://github.com/Human-Connection/Nitro-Backend/tree/master/kubernetes) - diff --git a/backend/installation/kubernetes.md b/backend/installation/kubernetes.md new file mode 100644 index 000000000..e5848d561 --- /dev/null +++ b/backend/installation/kubernetes.md @@ -0,0 +1,5 @@ +# Kubernetes + +Currently you can find some documentation here: +[https://github.com/Human-Connection/Nitro-Deployment](https://github.com/Human-Connection/Nitro-Deployment) + diff --git a/backend/installation/configuration.md b/backend/installation/local-backend.md similarity index 57% rename from backend/installation/configuration.md rename to backend/installation/local-backend.md index 31101382a..2cfedbe81 100644 --- a/backend/installation/configuration.md +++ b/backend/installation/local-backend.md @@ -1,20 +1,98 @@ -# Neo4j Installation and Configuration +# Local Installation -## Configure Enviroment +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: + +```bash +$ 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 +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +$ npm install +``` +{% endtab %} +{% endtabs %} + +## Start the Server + +{% tabs %} +{% tab title="Yarn" %} + +### Development + +```bash +$ yarn run dev +``` + +### Production + +```bash +# you will need to build the app first +$ yarn run build +# run after build (dist folder must exist) +$ yarn run start +``` + +{% endtab %} +{% tab title="NPM" %} + +### Development + +```bash +$ npm run dev +``` + +### Production + +```bash +# you will need to build the app first +$ npm run build +# run after build (dist folder must exist) +$ 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. + +{% 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 following step … +{% endhint %} + +## Neo4j Installation and Configuration + +### Configure Environment Set your Neo4j connection string and credentials in `.env`. For example: {% code-tabs %} {% code-tabs-item title=".env" %} + ```yaml NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=letmein ``` + {% endcode-tabs-item %} {% endcode-tabs %} -## Neo4j Installation +### Neo4j Installation {% hint style="warning" %} You **need to install APOC** as a plugin for the graph you create in neo4j! @@ -24,6 +102,7 @@ Note that grand-stack-starter does not currently bundle a distribution of 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) @@ -46,23 +125,42 @@ In the **Human Connection DB** area is a **Manage** button. By clicking it the a 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](configuration.md#configure-environment) above. -{% endtab %} +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](docker-backend.md#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** +#### Install APOC plugin on Debian-based systems 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 +```bash +$ 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 +### Database Informations and Commands via Browser + +Information about your Neo4j database can be obtained in your browser via [http://localhost:7474/browser/](http://localhost:7474/browser/). +You can even send commands to Neo4j here. For example, for creating indices, as described in the next step. + +### Create Indices in Neo4j + +{% hint style="info" %} +TODO: Is there a terminal command to create indices in Neo4j, because that would be a more general solution … +{% endhint %} + +To create the required indexes in Neo4j, you must send the following command to the database using the [browser command line](#database-informations-and-commands-via-browser), see above. + +```sh +$ CALL db.index.fulltext.createNodeIndex("full_text_search",["Post"],["title", "content"]); +``` + +### 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. @@ -81,4 +179,3 @@ $ 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. - diff --git a/documentation/edit-this-documentation.md b/documentation/edit-this-documentation.md index 7f699e5e3..5c52ad52d 100644 --- a/documentation/edit-this-documentation.md +++ b/documentation/edit-this-documentation.md @@ -118,4 +118,3 @@ TODO: How to modify screenshots in Linux ... {% endhint %} {% endtab %} {% endtabs %} - diff --git a/workflow/pull-requests.md b/workflow/README.md similarity index 98% rename from workflow/pull-requests.md rename to workflow/README.md index 046d9f16c..ce97c37b8 100644 --- a/workflow/pull-requests.md +++ b/workflow/README.md @@ -3,4 +3,3 @@ {% hint style="info" %} TODO: How to Contribute... {% endhint %} - diff --git a/workflow/contribute/github-workflow.md b/workflow/contribute/github-workflow.md new file mode 100644 index 000000000..08e2474f5 --- /dev/null +++ b/workflow/contribute/github-workflow.md @@ -0,0 +1,5 @@ +# Our GitHub Workflow + +{% hint style="info" %} +TODO: Git and GitHub Workflow … (best practice) +{% endhint %}