From 2008871ee4a7219c7fd52d130f7749ccf1d2591f Mon Sep 17 00:00:00 2001
From: Yassin Eldeeb <yassineldeeb94@gmail.com>
Date: Wed, 25 Jan 2023 12:36:48 +0200
Subject: [PATCH] docs: filling the gaps of self hosted guide (#863)

Co-authored-by: Kamil Kisiela <kamil.kisiela@gmail.com>
---
 .../src/pages/self-hosting/get-started.mdx    | 181 ++++++++++++++++--
 1 file changed, 169 insertions(+), 12 deletions(-)

diff --git a/packages/web/docs/src/pages/self-hosting/get-started.mdx b/packages/web/docs/src/pages/self-hosting/get-started.mdx
index 5035a7ee5..6fd389d77 100644
--- a/packages/web/docs/src/pages/self-hosting/get-started.mdx
+++ b/packages/web/docs/src/pages/self-hosting/get-started.mdx
@@ -29,7 +29,7 @@ proceeding.
 
 ## Quick Start Video
 
-Int this video you will learn how to run GraphQL Hive and publish your first schema on your machine
+In this video you will learn how to run GraphQL Hive and publish your first schema on your machine
 in less than 15 minutes.
 
 <iframe
@@ -41,13 +41,21 @@ in less than 15 minutes.
 
 First download the `docker-compose.community.yml` file from the
 [GitHub repository](https://github.com/kamilkisiela/graphql-hive/blob/main/docker/docker-compose.community.yml)
-using `wget`.
+using `wget`. This's going to download the latest version available.
 
-```bash
-wget https://raw.githubusercontent.com/kamilkisiela/graphql-hive/main/docker/docker-compose.community.yml
-```
+<Callout type="info">
+  Note: make sure you've Docker installed to be able to continue with the setup process.
+</Callout>
 
-After downloading the file, you need to set some environment variables.
+> You can also download the file directly from GitHub, if you don't have wget installed using the link
+> below 
+> ```sh
+> bash wget https://raw.githubusercontent.com/kamilkisiela/graphql-hive/main/docker-compose.community.yml
+> ```
+
+After downloading the `docker-compose.community.yml` file, this includes all the services required
+for running Hive locally in a self hosted environment. But before we can spin it up, we first need
+to set some environment variables.
 
 <Callout>
   **Docker Tag.** Docker images are built and published for each single commit within the GraphQL
@@ -63,7 +71,7 @@ After downloading the file, you need to set some environment variables.
 
 ```bash
 export DOCKER_REGISTRY="ghcr.io/kamilkisiela/graphql-hive/"
-export DOCKER_TAG=":latest"
+export DOCKER_TAG=":latest" # Pin this to an exact commit hash from our `main` branch, we publish a Docker image per each commit on main, and for PRs.
 export HIVE_ENCRYPTION_SECRET=$(openssl rand -hex 16)
 export HIVE_APP_BASE_URL="http://localhost:8080"
 export HIVE_EMAIL_FROM="no-reply@graphql-hive.com"
@@ -89,25 +97,174 @@ the environment variables.
 
 </Callout>
 
-After setting the environment variables, you can start the GraphQL Hive services using
-`docker-compose`.
+After setting the environment variables, pull the required images for GraphQL Hive services. This's
+going to take some time if you're doing it for the first time.
 
 ```bash
-docker-compose -f docker-compose.community.yml up
-# or of you embedded the environment variables
-docker-compose -f docker-compose.with-env.yml up
+docker compose -f docker-compose.community.yml pull
+```
+
+After it's done, you can start the GraphQL Hive services using `docker compose`.
+
+```bash
+docker compose -f docker-compose.community.yml up
+# or of you embedded the environment variables into your docker compose file and called it `docker-compose.with-env.yml`
+docker compose -f docker-compose.with-env.yml up
 ```
 
 Wait until all the services are up and running.
 
 Congratulations 🥳, you just started your own GraphQL Hive instance.
 
+You'll notice the folder named `.hive` at your root directory that has been mounted from docker
+representing the volumes for the different storages used by Hive services like `postgres` and
+`minio`, etc... So yes data are currently local but we'll discuss that further more in the
+`Next Steps` section.
+
+> Note: deleting this directory will end up with a loss of data, as this directory is acting as a
+> volume for storing the data from Hive dependencies: database and storage
+
+## Testing GraphQL Hive
+
 Visit `http://localhost:8080` in your browser and start using GraphQL Hive! The usage reporting
 endpoint is bound to `http://localhost:8081`. The GraphQL API is bound to `http://localhost:8082`.
 The artifacts bucket is bound to `http://localhost:8083`.
 
+Firstly, you can head to `http://localhost:8080` in your browser and start using GraphQL Hive!
+You'll need to Sign Up for an account by inputting your email and password. And once you do you'll
+see your personal organization that has been automatically created for you by default.
+
+### Creating first project and target
+
+Now that we have GraphQL Hive setup locally, signed up and logged into our dashboard. We can start
+creating our first project which we're going to push graphql schemas to.
+
+So you're going to click on the `Create a Project` button on the top right, give it a name and
+choose your project type. You're going to see all sorts of types `Single` which is the most common
+and there're also `Federation` and `Stitching` but what's also nice is that you can define your own
+custom endpoints for schema validation and schema building. I'm going to go with `Single` but you
+can choose what best suits your needs. Then click `Create Project`, you're going to be redirected to
+your project page where you're going to see 3 listed targets created for you by default:
+
+- `development`
+- `production`
+- `staging`
+
+We're going to use the `development` target in this guide and as soon as you click it you'll see
+this message:
+
+> Hive is waiting for your first schema.
+>
+> You can publish a schema with Hive CLI and Hive Client
+
+If you already have a Nodejs project with a graphql schema that's great you can skip over the next
+step, but if not so we're going to initialize a new package in our directory, you can use your
+preferred package manager to do so:
+
+```bash
+# you can do the same with npm or yarn
+pnpm init
+```
+
+Then create a `schema.graphql` file wherever you want, you can put it at the root for example with
+any simple graphql schema like the following:
+
+```graphql
+type Query {
+  hello: String!
+}
+```
+
+You also need to have a git repository initilaized for your project, because Hive automatically uses
+the last commit hash to determine who the author is and ties the schema with the commit hash. So
+we're going to do that.
+
+```bash
+git init
+```
+
+Make sure you exclude the following in your `.gitignore` file, because you don't wanna push those in
+your commits:
+
+```
+node_modules
+.hive
+hive.json
+.env
+```
+
+Make sure to at least have a single commit so that Hive can associate the schema with it.
+
+```bash
+git add .
+git commit -m"init"
+```
+
+Now that you've your Nodejs project setup, start by installing the GraphQL Hive CLI which we're
+going to use to interact with Hive's server.
+
+```bash
+# you can do the same with npm or yarn
+pnpm i -D @graphql-hive/cli
+```
+
+<Callout type="info">
+  We recommend that you install the GraphQL Hive CLI as a dev dependency
+</Callout>
+
+After installing it, the CLI's bin is set to `hive` which means you can check if it was installed by
+using this command:
+
+```bash
+# you can do the same with npm or yarn
+pnpm hive --version
+```
+
+Make sure you get an output specifiying the installed version for your CLI.
+
+And since we're using the Self Hosted version, we need to configure the Hive CLI to use our local
+endpoint, by creating a `hive.json` file at the root of your directory. Then specify the `registry`
+key to point it our local registry instead of the cloud version one and the value is going to be
+`http://localhost:8082/graphql` where its running.
+
+Additionally the schemas registry only allows trusted sources to be able to push to them, so we have
+to create an access token by heading back to our project page, specifically on the target(in this
+guide it's `development`) then go to the settings tab, if you scroll donw a bit you're going to see
+the `Tokens` section, click the `Generate New Token` button, give it a name then we'll have to set
+some permissions for that token, so expand the `All targets` section then give the `Registry` a
+`Read & Write` access. Click the `Generate Token` button, then copy the token value. Head back to
+the `hive.json` config file then add a new key `token` and paste the value from your clipboard.
+
+Now we're all setup to use the GraphQL Hive CLI against our Setup!
+
+We can publish our first schema by using:
+
+```bash
+pnpm hive schema:publish ./schema.graphql
+```
+
+Go to the `Schema` tab in your project target and you're going to see your latest published schema.
+
+## Bounded Ports Reference
+
+| Port | Purpose                      |
+| ---- | ---------------------------- |
+| 8080 | Hive's Main App UI           |
+| 8081 | The Usage Reporting Endpoint |
+| 8082 | The GraphQL API              |
+| 8083 | The Artifacts Bucket         |
+
 ## Next Steps
 
+## Bounded Ports Reference
+
+| Port | Purpose                      |
+| ---- | ---------------------------- |
+| 8080 | Hive's Main App UI           |
+| 8081 | The Usage Reporting Endpoint |
+| 8082 | The GraphQL API              |
+| 8083 | The Artifacts Bucket         |
+
 After doing your first testing with GraphQL Hive you should consider the following steps:
 
 - Evaluate whether you want to run Databases yourself within Docker or instead use a managed