Yorkie

Minikube Installation

Minikube is a tool that makes it easy to run Kubernetes locally.

In this guide, you will install Yorkie cluster on minikube using Helm. Then, you will test Yorkie cluster with Quill Example to see how collaborative editing works with Yorkie.

Prerequisites

This tutorial assumes that you are familiar with Kubernetes and kubectl.

For this tutorial, you will need:

Setup minikube on your machine

First, you need to setup minikube on your machine to use Kubernetes locally and deploy Yorkie cluster.

Start Minikube with the following command:

$ minikube start

After Minikube is started, you will see the following output:

...
🔎  Verifying Kubernetes components...
🌟  Enabled addons: default-storageclass, storage-provisioner
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Then, you need to enable ingress addons to expose Yorkie cluster with nginx ingress controller.

Enable ingress addons with the following command:

$ minikube addons enable ingress

After ingress addons are enabled, you will see the following output:

...
🔎  Verifying ingress addon...
🌟  The 'ingress' addon is enabled

Install Istio with istioctl

After Minikube is configured, you need to install Istio for Yorkie cluster. Yorkie cluster uses Istio for L7 load balancing and traffic management.

First, create the yorkie namespace with the following command:

$ kubectl create namespace yorkie

Then, install Istio with the following command:

$ istioctl install -f <(curl -s https://raw.githubusercontent.com/yorkie-team/yorkie/main/build/charts/yorkie-cluster/istio-operator.yaml)

This will install Istio with Istio Operator configuration file. You can find the configuration file here.

When installing Istio, you will see the following output:

This will install the Istio 1.17.1 default profile with ["Istio core" "Istiod" "Ingress gateways"] components into the cluster. Proceed? (y/N)

Type y and press Enter to continue.

After Istio is installed, you will see the following output:

✔ Istio core installed
✔ Istiod installed
✔ Ingress gateways installed
✔ Installation complete                                                                                             
Making this installation the default for injection and validation.


Thank you for installing Istio 1.17.  Please take a few minutes to tell us about your install/upgrade experience!  https://forms.gle/hMHGiwZHPU7UQRWe9

Setup MongoDB pod and service

Before installing the Yorkie cluster with Helm chart, you need to set up a MongoDB pod and expose it as a service. This is crucial since internal MongoDB installation is no longer provided.

First, create the mongodb namespace with the following command:

$ kubectl create namespace mongodb

Then, create a MongoDB pod named mongodb in the mongodb namespace with the following command:

$ kubectl run mongodb --image=mongo:latest --port=27017 -n mongodb

Next, expose the MongoDB pod as a service to allow other pods to access it with the following command:

$ kubectl expose pod mongodb --port=27017 --target-port=27017 --name=mongodb --type=ClusterIP -n mongodb

By following these steps, you ensure that the MongoDB pod is running and accessible to other pods within the cluster.

Add yorkie-team Helm chart in your local repository

After Istio is installed, you need to add yorkie-team Helm chart repository in your local repository to install Yorkie cluster.

Add yorkie-team Helm chart repository in your local repository with the following command:

$ helm repo add yorkie-team https://yorkie-team.github.io/yorkie/helm-charts

Then, update your local repository with the following command:

$ helm repo update

Install Yorkie cluster with Helm chart

Now you have added yorkie-team Helm chart repository in your local repository, you can install Yorkie cluster with Helm chart.

Install Yorkie cluster with the following command:

$ helm install yorkie-cluster yorkie-team/yorkie-cluster

This will install yorkie-cluster release in minikube cluster.

You can also set other Helm chart configuration options. For more information about Helm chart configuration, see Yorkie Cluster Helm Chart Configuration.

After Yorkie cluster is installed, you will see the following output:

NAME: yorkie-cluster
LAST DEPLOYED: Thu Apr 27 21:49:06 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
--- Install Complete ---
yorkie-cluster successfully installed!


For next steps, follow:
  $ curl https://github.com/yorkie-team/yorkie/tree/main/charts/yorkie-cluster


To learn more about the release, try:
  $ helm status yorkie-cluster
  $ helm get all yorkie-cluster

Now you have Yorkie cluster installed on your local machine.

It will take a few minutes for pods to be ready, so wait until all pods are ready. You can check the status of pods with the following command:

$ kubectl get pods -n yorkie --watch

After all pods are ready, you will see the following output:

NAME                             READY   STATUS    RESTARTS   AGE
yorkie-f595554db-48s9c           1/1     Running   0          8m18s
yorkie-f595554db-nggr9           1/1     Running   0          8m18s
yorkie-f595554db-z5jgs           1/1     Running   0          8m18s
yorkie-gateway-844d8c87d-fqpsk   1/1     Running   0          9m55s

Expose Yorkie cluster with Minikube tunnel

After you have installed Yorkie cluster, you need to expose Yorkie cluster with Minikube tunnel to access Yorkie cluster from your local machine.

Expose Yorkie cluster with Minikube tunnel with the following command:

$ minikube tunnel

When Minikube tunnel is started, you will see the following output:

✅  Tunnel successfully started


📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...


❗  The service/ingress yorkie requires privileged ports to be exposed: [80 443]
🔑  sudo permission will be asked for it.
🏃  Starting tunnel for service yorkie.
Password:

Enter your password and press Enter to continue.

You need to keep Minikube tunnel running while you are using Yorkie cluster.

This will expose Yorkie cluster via minikube cluster's IP address. You can check the IP address with the following command:

$ minikube ip

Test Yorkie cluster

Now that you have Yorkie cluster installed and exposed, you can test Yorkie cluster with yorkie-js-sdk, a JavaScript SDK for Yorkie.

Clone yorkie-js-sdk repository with the following command:

$ git clone https://github.com/yorkie-team/yorkie-js-sdk

Then, change directory to yorkie-js-sdk folder and install dependencies with the following command:

$ cd yorkie-js-sdk
$ pnpm i

After dependencies are installed, you need to set VITE_YORKIE_API_ADDR in the .env file to your minikube IP address with the following command:

$ cd examples/vanilla-quill
$ vi .env


VITE_YORKIE_API_ADDR=http://<minikube-ip>
# If you are using macOS, you should set VITE_YORKIE_API_ADDR to localhost instead of minikube-ip.
# VITE_YORKIE_API_ADDR=http://localhost
If you are using macOS, you should set VITE_YORKIE_API_ADDR to localhost instead of minikube ip.

Then, start Quill Example with the following command:

$ cd ../..
$ pnpm vanilla-quill dev


> yorkie-js@0.0.0 vanilla-quill /yorkie-js-sdk
> pnpm --filter=vanilla-quill "dev"




> vanilla-quill@0.0.0 dev /yorkie-js-sdk/examples/vanilla-quill
> vite




  VITE v5.3.5  ready in 178 ms


  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

You can open several web browsers and access http://localhost:5173 to test collaborative editing with Quill.

For more examples of collaborative tools developed with Yorkie, including Quill, take a look at yorkie-js-sdk examples.

Clean up Yorkie cluster

You have now installed Yorkie cluster on your local machine, and tested collaborative editing with Quill.

To learn about how to configure Yorkie Cluster in Helm Chart, see Yorkie Cluster Helm Chart Repository.

First, stop Quill Example and remove repository folder with the following command: Use Ctrl + C to stop Quill Example.

VITE v5.3.5  ready in 178 ms


  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help


# Stop Quill
$ ^C


# Remove repository folder
$ cd ..
$ rm -rf yorkie-js-sdk

Then, stop minikube tunnel in running terminal. Use Ctrl + C to stop minikube tunnel.

🏃  Starting tunnel for service yorkie.
Password:


# Stop minikube tunnel
$ ^C


✋  Stopped tunnel for service yorkie.

Then, uninstall Yorkie cluster with the following command:

$ helm uninstall yorkie-cluster
release "yorkie-cluster" uninstalled

Then, uninstall Istio with the following command:

$ istioctl uninstall --purge
All Istio resources will be pruned from the cluster
Proceed? (y/N) y
...
✔ Uninstall complete


# (Optional) Remove istio-system namespace
$ kubectl delete namespace istio-system

After that, you can stop minikube with the following command:

$ minikube stop
✋  Stopping node "minikube"  ...
🛑  Powering off "minikube" via SSH ...
🛑  1 node stopped.

You can delete minikube cluster with the following command:

$ minikube delete
🔥  Deleting "minikube" in docker ...
🔥  Deleting container "minikube" ...
🔥  Removing /Users/yorkie/.minikube/machines/minikube ...
💀  Removed all traces of the "minikube" cluster.

Next Steps

You can also install Yorkie cluster addons to monitor metrics and perform GitOps on Yorkie cluster.