diff --git a/archived/ha-cluster copy.md b/archived/ha-cluster copy.md new file mode 100644 index 00000000..e2976368 --- /dev/null +++ b/archived/ha-cluster copy.md @@ -0,0 +1,345 @@ ++++ +date = "2017-03-20T22:25:17+11:00" +title = "HA Cluster Setup" +weight = 5 +type = "docs" +[menu.main] + parent = "installation" ++++ + +You can run three Dgraph Alpha servers and three Dgraph Zero servers in a highly available cluster setup. For a highly available setup, start the Dgraph Zero server with `--replicas 3` flag, so that all data is replicated on three Alpha servers and forms one Alpha group. You can install a highly available cluster using: +* [dgraph-ha.yaml](https://github.com/dgraph-io/dgraph/blob/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml) file +* Helm charts. + +### Install a highly available Dgraph cluster using YAML or Helm + +{{% tabs %}} {{< tab "YAML" >}} +#### Before you begin: + +* Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +* Ensure that you have a production-ready Kubernetes cluster with at least three worker nodes running in a cloud provider of your choice. +* (Optional) To run Dgraph Alpha with TLS, see [TLS Configuration]({{< relref "tls-configuration.md" >}}). + +#### Installing a highly available Dgraph cluster + +1. Verify that you are able to access the nodes in the Kubernetes cluster: + + ```bash + kubectl get nodes + ``` + + An output similar to this appears: + + ```bash + NAME STATUS ROLES AGE VERSION + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ``` + After your Kubernetes cluster is up, you can use [dgraph-ha.yaml](https://github.com/dgraph-io/dgraph/blob/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml) to start the cluster. + +1. Start a StatefulSet that creates Pods with `Zero`, `Alpha`, and `Ratel UI`: + + ```bash + kubectl create --filename https://raw.githubusercontent.com/dgraph-io/dgraph/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml + ``` + An output similar to this appears: + + ```bash + service/dgraph-zero-public created + service/dgraph-alpha-public created + service/dgraph-ratel-public created + service/dgraph-zero created + service/dgraph-alpha created + statefulset.apps/dgraph-zero created + statefulset.apps/dgraph-alpha created + deployment.apps/dgraph-ratel created + ``` +1. Confirm that the Pods were created successfully. + + ```bash + kubectl get pods + ``` + An output similar to this appears: + + ```bash + NAME READY STATUS RESTARTS AGE + dgraph-alpha-0 1/1 Running 0 6m24s + dgraph-alpha-1 1/1 Running 0 5m42s + dgraph-alpha-2 1/1 Running 0 5m2s + dgraph-ratel- 1/1 Running 0 6m23s + dgraph-zero-0 1/1 Running 0 6m24s + dgraph-zero-1 1/1 Running 0 5m41s + dgraph-zero-2 1/1 Running 0 5m6s + ``` + You can check the logs for the Pod using `kubectl logs --follow `.. + +1. Port forward from your local machine to the Pod: + + ```bash + kubectl port-forward service/dgraph-alpha-public 8080:8080 + kubectl port-forward service/dgraph-ratel-public 8000:8000 + ``` +1. Go to `http://localhost:8000` to access Dgraph using the Ratel UI. + +{{% notice "note" %}} You can also access the service on its External IP address.{{% /notice %}} + +#### Deleting highly available Dgraph resources + +Delete all the resources using: + +```sh +kubectl delete --filename https://raw.githubusercontent.com/dgraph-io/dgraph/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml +kubectl delete persistentvolumeclaims --selector app=dgraph-zero +kubectl delete persistentvolumeclaims --selector app=dgraph-alpha +``` +{{< /tab >}} +{{< tab "Helm" >}} + +#### Before you begin + +* Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +* Ensure that you have a production-ready Kubernetes cluster with atleast three worker nodes running in a cloud provider of your choice. +* Install [Helm](https://helm.sh/docs/intro/install/). +* (Optional) To run Dgraph Alpha with TLS, see [TLS Configuration]({{< relref "tls-configuration.md" >}}). + +#### Installing a highly available Dgraph cluster using Helm + +1. Verify that you are able to access the nodes in the Kubernetes cluster: + + ```bash + kubectl get nodes + ``` + + An output similar to this appears: + + ```bash + NAME STATUS ROLES AGE VERSION + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ..compute.internal Ready 1m v1.15.11-eks-af3caf + ``` + After your Kubernetes cluster is up and running, you can use of the [Dgraph Helm chart](https://github.com/dgraph-io/charts/) to install a highly available Dgraph cluster + +1. Add the Dgraph helm repository:: + + ```bash + helm repo add dgraph https://charts.dgraph.io + ``` +1. Install the chart with ``: + + ```bash + helm install dgraph/dgraph + ``` + + You can also specify the version using: + ```bash + helm install dgraph/dgraph --set image.tag="{{< version >}}" + ``` + When configuring the Dgraph image tag, be careful not to use `latest` or `main` in a production environment. These tags may have the Dgraph version change, causing a mixed-version Dgraph cluster that can lead to an outage and potential data loss. + + An output similar to this appears: + + ```bash + NAME: + LAST DEPLOYED: Wed Feb 1 21:26:32 2023 + NAMESPACE: default + STATUS: deployed + REVISION: 1 + TEST SUITE: None + NOTES: + 1. You have just deployed Dgraph, version 'v21.12.0'. + + For further information: + * Documentation: https://dgraph.io/docs/ + * Community and Issues: https://discuss.dgraph.io/ + 2. Get the Dgraph Alpha HTTP/S endpoint by running these commands. + export ALPHA_POD_NAME=$(kubectl get pods --namespace default --selector "statefulset.kubernetes.io/pod-name=-dgraph-alpha-0,release=-dgraph" --output jsonpath="{.items[0].metadata.name}") + echo "Access Alpha HTTP/S using http://localhost:8080" + kubectl --namespace default port-forward $ALPHA_POD_NAME 8080:8080 + + NOTE: Change "http://" to "https://" if TLS was added to the Ingress, Load Balancer, or Dgraph Alpha service. + ``` +1. Get the name of the Pods in the cluster using `kubectl get pods`: + ```bash + NAME READY STATUS RESTARTS AGE + -dgraph-alpha-0 1/1 Running 0 4m48s + -dgraph-alpha-1 1/1 Running 0 4m2s + -dgraph-alpha-2 1/1 Running 0 3m31s + -dgraph-zero-0 1/1 Running 0 4m48s + -dgraph-zero-1 1/1 Running 0 4m10s + -dgraph-zero-2 1/1 Running 0 3m50s + +1. Get the Dgraph Alpha HTTP/S endpoint by running these commands: + ```bash + export ALPHA_POD_NAME=$(kubectl get pods --namespace default --selector "statefulset.kubernetes.io/pod-name=-dgraph-alpha-0,release=-dgraph" --output jsonpath="{.items[0].metadata.name}") + echo "Access Alpha HTTP/S using http://localhost:8080" + kubectl --namespace default port-forward $ALPHA_POD_NAME 8080:8080 + ``` +#### Deleting the resources from the cluster + +1. Delete the Helm deployment using: + + ```sh + helm delete my-release + ``` +2. Delete associated Persistent Volume Claims: + + ```sh + kubectl delete pvc --selector release=my-release + ``` +{{< /tab >}} +{{% /tabs %}} + + +### Dgraph configuration files + +You can create a Dgraph [Config]({{< relref "cli/config" >}}) files for Alpha server and Zero server with Helm chart configuration values, ``. For more information about the values, see the latest [configuration settings](https://github.com/dgraph-io/charts/blob/master/charts/dgraph/README.md#configuration). + +1. Open an editor of your choice and create a config file named `.yaml`: + +```yaml +# .yaml +alpha: + configFile: + config.yaml: | + alsologtostderr: true + badger: + compression_level: 3 + tables: mmap + vlog: mmap + postings: /dgraph/data/p + wal: /dgraph/data/w +zero: + configFile: + config.yaml: | + alsologtostderr: true + wal: /dgraph/data/zw +``` + +2. Change to the director in which you created ``.yaml and then install with Alpha and Zero configuration using: + +```sh +helm install dgraph/dgraph --values .yaml +``` + +### Exposing Alpha and Ratel Services + +By default Zero and Alpha services are exposed only within the Kubernetes cluster as +Kubernetes service type `ClusterIP`. + +In order to expose the Alpha service and Ratel service publicly you can use Kubernetes service type `LoadBalancer` or an Ingress resource. + +{{% tabs %}} {{< tab "LoadBalancer" >}} + +##### Public Internet + +To use an external load balancer, set the service type to `LoadBalancer`. + +{{% notice "note" %}}For security purposes we recommend limiting access to any public endpoints, such as using a white list.{{% /notice %}} + +1. To expose Alpha service to the Internet use: + +```sh +helm install dgraph/dgraph --set alpha.service.type="LoadBalancer" +``` + +2. To expose Alpha and Ratel services to the Internet use: + +```sh +helm install dgraph/dgraph --set alpha.service.type="LoadBalancer" --set ratel.service.type="LoadBalancer" +``` + +##### Private Internal Network + +An external load balancer can be configured to face internally to a private subnet rather the public Internet. This way it can be accessed securely by clients on the same network, through a VPN, or from a jump server. In Kubernetes, this is often configured through service annotations by the provider. Here's a small list of annotations from cloud providers: + +|Provider | Documentation Reference | Annotation | +|------------|---------------------------|------------| +|AWS |[Amazon EKS: Load Balancing](https://docs.aws.amazon.com/eks/latest/userguide/load-balancing.html)|`service.beta.kubernetes.io/aws-load-balancer-internal: "true"`| +|Azure |[AKS: Internal Load Balancer](https://docs.microsoft.com/azure/aks/internal-lb)|`service.beta.kubernetes.io/azure-load-balancer-internal: "true"`| +|Google Cloud|[GKE: Internal Load Balancing](https://cloud.google.com/kubernetes-engine/docs/how-to/internal-load-balancing)|`cloud.google.com/load-balancer-type: "Internal"`| + + +As an example, using Amazon [EKS](https://aws.amazon.com/eks/) as the provider. + +1. Create a Helm chart configuration values file ``.yaml file: + +```yaml +# .yaml +alpha: + service: + type: LoadBalancer + annotations: + service.beta.kubernetes.io/aws-load-balancer-internal: "true" +ratel: + service: + type: LoadBalancer + annotations: + service.beta.kubernetes.io/aws-load-balancer-internal: "true" +``` + +1. To expose Alpha and Ratel services privately, use: + +```sh +helm install dgraph/dgraph --values .yaml +``` +{{% /tab %}} +{{% tab "Ingress Resource" %}} + +You can expose Alpha and Ratel using an [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource that can route traffic to service resources. Before using this option you may need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) first, as is the case with [AKS](https://docs.microsoft.com/azure/aks/) and [EKS](https://aws.amazon.com/eks/), while in the case of [GKE](https://cloud.google.com/kubernetes-engine), this comes bundled with a default ingress controller. When routing traffic based on the `hostname`, you may want to integrate an addon like [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) so that DNS records can be registered automatically when deploying Dgraph. + +As an example, you can configure a single ingress resource that uses [ingress-nginx](https://github.com/kubernetes/ingress-nginx) for Alpha and Ratel services. + +1. Create a Helm chart configuration values file, ``.yaml file: + +```yaml +# .yaml +global: + ingress: + enabled: false + annotations: + kubernetes.io/ingress.class: nginx + ratel_hostname: "ratel." + alpha_hostname: "alpha." +``` + +2. To expose Alpha and Ratel services through an ingress: + +```sh +helm install dgraph/dgraph --values .yaml +``` + +You can run `kubectl get ingress` to see the status and access these through their hostname, such as `http://alpha.` and `http://ratel.` + + +{{% notice "tip" %}}Ingress controllers will likely have an option to configure access for private internal networks. Consult documentation from the ingress controller provider for further information.{{% /notice %}} +{{% /tab %}}{{% /tabs %}} + +### Upgrading the Helm chart + +You can update your cluster configuration by updating the configuration of the +Helm chart. Dgraph is a stateful database that requires some attention on +upgrading the configuration carefully in order to update your cluster to your +desired configuration. + +In general, you can use [`helm upgrade`][helm-upgrade] to update the +configuration values of the cluster. Depending on your change, you may need to +upgrade the configuration in multiple steps. + +[helm-upgrade]: https://helm.sh/docs/helm/helm_upgrade/ + +To upgrade to an HA cluster setup: + +1. Ensure that the shard replication setting is more than one and `zero.shardReplicaCount`. For example, set the shard replica flag on the Zero node group to 3,`zero.shardReplicaCount=3`. +2. Run the Helm upgrade command to restart the Zero node group: + ```sh + helm upgrade dgraph/dgraph [options] + ``` +3. Set the Alpha replica count flag. For example: `alpha.replicaCount=3`. +4. Run the Helm upgrade command again: + ```sh + helm upgrade dgraph/dgraph [options] + ``` + + diff --git a/content/installation/kubernetes/monitoring-cluster.md b/archived/monitoring-cluster.md similarity index 100% rename from content/installation/kubernetes/monitoring-cluster.md rename to archived/monitoring-cluster.md diff --git a/content/installation/kubernetes/single-server-cluster.md b/archived/single-server-cluster.md similarity index 100% rename from content/installation/kubernetes/single-server-cluster.md rename to archived/single-server-cluster.md diff --git a/content/installation/deployment-patterns.md b/content/installation/deployment-patterns.md index af49c8b1..b3bad754 100644 --- a/content/installation/deployment-patterns.md +++ b/content/installation/deployment-patterns.md @@ -20,41 +20,7 @@ This guide covers different Dgraph deployment patterns, from simple development --- -## Learning Environment - -**Best for:** First-time users, tutorials, local experimentation - -### Docker - -```sh -docker run -d -p 8080:8080 -p 9080:9080 \ - -v ~/dgraph:/dgraph \ - --name dgraph \ - dgraph/standalone:latest -``` - -**Includes:** Zero + Alpha in one container -**Access:** Ratel UI at `http://localhost:8080` - -### Command Line (Linux) - -```sh -# Terminal 1: Start Zero -dgraph zero --my=localhost:5080 - -# Terminal 2: Start Alpha -dgraph alpha --my=localhost:7080 --zero=localhost:5080 -``` - -**Key Flags:** -- `--my`: Address and port that other nodes will connect to (default: `localhost:5080` for Zero, `localhost:7080` for Alpha) -- `--zero`: Alpha connects to Zero using this address -- `--wal`: Directory for write-ahead log entries (default: `zw` for Zero, `w` for Alpha) -- `--postings`: Directory for Alpha data storage (default: `p`) -- `--bindall`: Set to `true` for machine-to-machine communication (default: `true`) - -**Pros:** Quick to start, minimal resources -**Cons:** No HA, no persistence guarantees, not for production +> **Getting Started?** For first-time users and local development, see the [Learning Environment]({{< relref "single-host-setup.md" >}}) guide, which covers Docker standalone and Docker Compose setups with Ratel UI. --- @@ -74,54 +40,9 @@ dgraph alpha --my=localhost:7080 --zero=localhost:5080 └──────────────┘ ``` -### Docker Compose - -```yaml -version: "3.8" -services: - zero: - image: dgraph/dgraph:latest - volumes: - - dgraph-zero:/dgraph - ports: - - 5080:5080 - - 6080:6080 - command: dgraph zero --my=zero:5080 - - alpha: - image: dgraph/dgraph:latest - volumes: - - dgraph-alpha:/dgraph - ports: - - 8080:8080 - - 9080:9080 - command: dgraph alpha --my=alpha:7080 --zero=zero:5080 - -volumes: - dgraph-zero: - dgraph-alpha: -``` - -Start with: `docker-compose up -d` - -### Command Line - -```sh -# Start Zero -dgraph zero --my=:5080 -w data/zero - -# Start Alpha -dgraph alpha --my=:7080 --zero=:5080 -p data/alpha/p -w data/alpha/w -``` -**Flag Reference:** -- `-w` / `--wal`: Directory for write-ahead log entries -- `-p` / `--postings`: Directory for Alpha data storage -- `--bindall`: Set to `true` for network communication (default: `true`) -- `--v=2`: Recommended log verbosity level for better diagnostics -**Pros:** Realistic setup, persistent storage -**Cons:** No HA, single point of failure +Refer to [Basic Cluster]({{< relref "single-host-setup.md" >}}) instructions. --- diff --git a/content/installation/kubernetes/ha-cluster.md b/content/installation/ha-cluster.md similarity index 75% rename from content/installation/kubernetes/ha-cluster.md rename to content/installation/ha-cluster.md index a5823422..3d98c413 100644 --- a/content/installation/kubernetes/ha-cluster.md +++ b/content/installation/ha-cluster.md @@ -1,100 +1,13 @@ +++ date = "2017-03-20T22:25:17+11:00" -title = "Highly Available Cluster Setup" -weight = 4 +title = "HA Cluster Setup" +weight = 5 type = "docs" [menu.main] - parent = "kubernetes" + parent = "installation" +++ -You can run three Dgraph Alpha servers and three Dgraph Zero servers in a highly available cluster setup. For a highly available setup, start the Dgraph Zero server with `--replicas 3` flag, so that all data is replicated on three Alpha servers and forms one Alpha group. You can install a highly available cluster using: -* [dgraph-ha.yaml](https://github.com/dgraph-io/dgraph/blob/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml) file -* Helm charts. - -### Install a highly available Dgraph cluster using YAML or Helm - -{{% tabs %}} {{< tab "YAML" >}} -#### Before you begin: - -* Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -* Ensure that you have a production-ready Kubernetes cluster with at least three worker nodes running in a cloud provider of your choice. -* (Optional) To run Dgraph Alpha with TLS, see [TLS Configuration]({{< relref "tls-configuration.md" >}}). - -#### Installing a highly available Dgraph cluster - -1. Verify that you are able to access the nodes in the Kubernetes cluster: - - ```bash - kubectl get nodes - ``` - - An output similar to this appears: - - ```bash - NAME STATUS ROLES AGE VERSION - ..compute.internal Ready 1m v1.15.11-eks-af3caf - ..compute.internal Ready 1m v1.15.11-eks-af3caf - ..compute.internal Ready 1m v1.15.11-eks-af3caf - ``` - After your Kubernetes cluster is up, you can use [dgraph-ha.yaml](https://github.com/dgraph-io/dgraph/blob/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml) to start the cluster. - -1. Start a StatefulSet that creates Pods with `Zero`, `Alpha`, and `Ratel UI`: - - ```bash - kubectl create --filename https://raw.githubusercontent.com/dgraph-io/dgraph/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml - ``` - An output similar to this appears: - - ```bash - service/dgraph-zero-public created - service/dgraph-alpha-public created - service/dgraph-ratel-public created - service/dgraph-zero created - service/dgraph-alpha created - statefulset.apps/dgraph-zero created - statefulset.apps/dgraph-alpha created - deployment.apps/dgraph-ratel created - ``` -1. Confirm that the Pods were created successfully. - - ```bash - kubectl get pods - ``` - An output similar to this appears: - - ```bash - NAME READY STATUS RESTARTS AGE - dgraph-alpha-0 1/1 Running 0 6m24s - dgraph-alpha-1 1/1 Running 0 5m42s - dgraph-alpha-2 1/1 Running 0 5m2s - dgraph-ratel- 1/1 Running 0 6m23s - dgraph-zero-0 1/1 Running 0 6m24s - dgraph-zero-1 1/1 Running 0 5m41s - dgraph-zero-2 1/1 Running 0 5m6s - ``` - You can check the logs for the Pod using `kubectl logs --follow `.. - -1. Port forward from your local machine to the Pod: - - ```bash - kubectl port-forward service/dgraph-alpha-public 8080:8080 - kubectl port-forward service/dgraph-ratel-public 8000:8000 - ``` -1. Go to `http://localhost:8000` to access Dgraph using the Ratel UI. - -{{% notice "note" %}} You can also access the service on its External IP address.{{% /notice %}} - -#### Deleting highly available Dgraph resources - -Delete all the resources using: - -```sh -kubectl delete --filename https://raw.githubusercontent.com/dgraph-io/dgraph/main/contrib/config/kubernetes/dgraph-ha/dgraph-ha.yaml -kubectl delete persistentvolumeclaims --selector app=dgraph-zero -kubectl delete persistentvolumeclaims --selector app=dgraph-alpha -``` -{{< /tab >}} -{{< tab "Helm" >}} +You can run three Dgraph Alpha servers and three Dgraph Zero servers in a highly available cluster setup. For a highly available setup, start the Dgraph Zero server with `--replicas 3` flag, so that all data is replicated on three Alpha servers and forms one Alpha group. You can install a highly available cluster using Helm charts. #### Before you begin @@ -188,8 +101,6 @@ kubectl delete persistentvolumeclaims --selector app=dgraph-alpha ```sh kubectl delete pvc --selector release=my-release ``` -{{< /tab >}} -{{% /tabs %}} ### Dgraph configuration files diff --git a/content/installation/kubernetes/_index.md b/content/installation/kubernetes/_index.md deleted file mode 100644 index 74e892b2..00000000 --- a/content/installation/kubernetes/_index.md +++ /dev/null @@ -1,9 +0,0 @@ -+++ -title = "Production Environment" -weight = 4 -type = "docs" -[menu.main] - name = "Production Environment" - identifier = "kubernetes" - parent = "installation" -+++ \ No newline at end of file diff --git a/content/installation/lambda-server.md b/content/installation/lambda-server.md index 820cd6aa..20e9a7c0 100644 --- a/content/installation/lambda-server.md +++ b/content/installation/lambda-server.md @@ -2,20 +2,19 @@ title = "Lambda Server" description = "Setup a Dgraph database with a lambda server. Dgraph Lambda is a serverless platform for running JavaScript on Dgraph and Dgraph Cloud" aliases =['/graphql/lambda/server'] -weight = 3 +weight = 8 type = "docs" [menu.main] parent = "installation" +++ -In this article you'll learn how to setup a Dgraph database with a lambda server. -## Dgraph Lambda -[Dgraph Lambda](https://github.com/dgraph-io/dgraph-lambda) is a serverless platform for running JavaScript on Dgraph and [Dgraph Cloud](https://dgraph.io/cloud). - -You can [download the latest version](https://github.com/dgraph-io/dgraph-lambda/releases/latest) or review the implementation in our [open-source repository](https://github.com/dgraph-io/dgraph-lambda). +[Dgraph Lambda](https://github.com/dgraph-io/dgraph-lambda) is a component that allows you to execute custom business logic using JavaScript/TypeScript functions within your GraphQL API. It's part of Dgraph's GraphQL implementation and enables you to extend the auto-generated GraphQL API with custom resolvers. +{{%notice "note"%}} +Dgraph lambda is an optional server, only used for GraphQL API. +{{% /notice %}} ### Running with Docker diff --git a/content/installation/production-checklist.md b/content/installation/production-checklist.md index 7618f4b4..720be3a7 100644 --- a/content/installation/production-checklist.md +++ b/content/installation/production-checklist.md @@ -2,7 +2,7 @@ date = "2017-03-20T22:25:17+11:00" title = "Production checklist" description = "Requirements to install Dgraph in a production environment" -weight = 4 +weight = 9 type = "docs" [menu.main] parent = "installation" diff --git a/content/installation/single-host-setup.md b/content/installation/single-host-setup.md index c4d38158..91435243 100644 --- a/content/installation/single-host-setup.md +++ b/content/installation/single-host-setup.md @@ -1,7 +1,7 @@ +++ date = "2017-03-20T22:25:17+11:00" -title = "Learning Environment" -weight = 2 +title = "Basic cluster setup" +weight = 4 type = "docs" [menu.main] parent = "installation" @@ -11,30 +11,89 @@ type = "docs" -The recommended way to get started with Dgraph for local development is by using -the official Dgraph Docker image. +The recommended way to get started with Dgraph for local development is by using Docker. There are two main approaches: -### Start a standalone Dgraph cluster +## Option 1: Standalone Docker Image (Learning Environment) -The [`dgraph/standalone`](https://hub.docker.com/r/dgraph/standalone) Docker image has everything needed to run Dgraph locally. +The [`dgraph/standalone`](https://hub.docker.com/r/dgraph/standalone) Docker image is the fastest way to get started. This single container runs both Dgraph Zero and Dgraph Alpha, making it ideal for quick testing and development. -Ensure you have [Docker installed](https://www.docker.com/), then run the following command to start a local Dgraph instance: +Ensure you have [Docker installed](https://www.docker.com/), then run the following command: ```bash -docker run --name dgraph-dev -d -p 8080:8080 -p 9080:9080 dgraph/standalone:latest +docker run --name dgraph-dev -d -p 8080:8080 -p 9080:9080 \ + -v ~/dgraph:/dgraph \ + dgraph/standalone:latest ``` -This will create a local Dgraph instance and expose the ports necessary to connect to Dgraph via HTTP and gRPC. Specifically: +This command initiates a new Docker container +* `--name dgraph-dev` - creates a persistent container named `dgraph-dev` +* `-d` - runs the container in detached (daemon) mode +* `-p 8080:8080` - maps port 8080 for HTTP connections +* `-p 9080:9080` - maps port 9080 for gRPC connections +* `-v ~/dgraph:/dgraph` - persists data to your local `~/dgraph` directory +* `dgraph/standalone:latest` - uses the official Dgraph standalone image + +## Option 2: Docker Compose + +For a more production-like setup that separates Zero, Alpha, and Ratel into individual containers, use Docker Compose. This approach gives you better control and is easier to scale. + +Create a `docker-compose.yml` file with the following configuration: + +```yaml +version: '3.8' +name: dgraph-basic-cluster +services: + zero: + image: dgraph/dgraph:latest + ports: + - "5080:5080" + - "6080:6080" + command: dgraph zero --my=zero:5080 + restart: unless-stopped + + alpha: + image: dgraph/dgraph:latest + ports: + - "8080:8080" + - "9080:9080" + command: dgraph alpha --my=alpha:7080 --zero=zero:5080 --security whitelist=0.0.0.0/0 + depends_on: + - zero + restart: unless-stopped + + ratel: + image: dgraph/ratel:latest + ports: + - "8000:8000" + restart: unless-stopped -* `docker run` - initiates a new Docker container -* `--name dgraph-dev` - create a persistent docker imane named `dgraph-dev` -* `-d` - uses daemon mode -* `-p 8080:8080` - maps port 8080 from the host machine to port 8080 in the Docker container to allow Dgraph HTTP connections -* `-p 9080:9080` - maps port 9080 from the host machine to port 9080 in the Docker container to allow Dgraph gRPC connections -* `dgraph/standalone:latest` - specifies the Docker image to use, this is the official Dgraph image +``` + +Then start the cluster: + +```bash +docker-compose up -d +``` + +This starts three separate containers: +* **Zero**: Manages cluster membership and assigns UIDs (ports 5080, 6080) +* **Alpha**: Handles queries and mutations (ports 8080, 9080) +* **Ratel**: Web UI for interacting with Dgraph (port 8000) + +To stop the cluster: + +```bash +docker-compose down +``` + +To remove all data volumes: + +```bash +docker-compose down -v +``` ### Check your Dgraph cluster health -Verify your Dgraph instance using the `/heatlh` REST endpoint. +Verify your Dgraph instance using the `/health` REST endpoint. ```shell curl http://localhost:8080/health | jq @@ -62,18 +121,20 @@ The command should return basic cluster information: ] ``` -### Connect Ratel +### Access Ratel UI + Ratel is a web-based UI dashboard for interacting with Dgraph using Dgraph's query language, [DQL]({{}}). -Optionnaly, launch Ratel using the dgraph/ratel docker image : +**If using Option 1 (Standalone)**: Launch Ratel separately: -``` sh - docker run --name ratel -d -p "8000:8000" dgraph/ratel:latest +```bash +docker run --name ratel -d -p "8000:8000" dgraph/ratel:latest ``` -Navigate to Ratel at `http://localhosr:8000` and enter `http://localhost:8080` for the "Dgraph Conn String". -This will allow Ratel to connect to our local Dgraph instance and execute DQL queries. +**If using Option 2 (Docker Compose)**: Ratel is already included and will start automatically. + +Navigate to Ratel at `http://localhost:8000` and enter `http://localhost:8080` for the "Dgraph Conn String". This will allow Ratel to connect to your local Dgraph instance and execute DQL queries. - ![Setting up Ratel](/images/dgraph/quickstart/ratel-docker-connection.png) +![Setting up Ratel](/images/dgraph/quickstart/ratel-docker-connection.png)