Skip to content

Commit 5193c8f

Browse files
twosdaitwosdai
authored
Merge pull request #5 from marklogic/feature/CLD-421
Feature/cld 421
2 parents 7dabed2 + cba0f9d commit 5193c8f

File tree

1 file changed

+161
-0
lines changed

1 file changed

+161
-0
lines changed

‎docs/Local_Development_Tutorial.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Local Development Tutorial: Getting Started with MarkLogic in Kubernetes
2+
3+
# Table of contents
4+
* [Introduction](#Introduction)
5+
* [Prerequisites](##Prerequisites)
6+
* [Procedure](#Procedure)
7+
* [Setting Up Minikube](##Setting-Up-Minikube)
8+
* [Installing MarkLogic to Minikube](##Installing-a-Single-MarkLogic-Host-to-Minikube)
9+
* [Installing Multiple MarkLogic Hosts to Minikube](##Installing-Multiple-MarkLogic-Hosts-to-Minikube)
10+
* [Verifying the Installation](##Verifying-the-Installation)
11+
* [Debugging](#Debugging)
12+
* [Cleanup](#Cleanup)
13+
14+
# Introduction
15+
This tutorial describes how to set up local Kubernetes development environment with Minikube and MarkLogic Server. It covers these tasks:
16+
- Set up the prerequisites necessary for local development using MarkLogic Server in Kubernetes
17+
- How to run Minikube and load MarkLogic Server into the Kubernetes cluster
18+
- Access the MarkLogic Server cluster
19+
- How to debug the Kubernetes environment
20+
- How to clean up your environment
21+
22+
23+
## Prerequisites
24+
The following steps assume you are running this tutorial from a desktop environment. Mobile environments will likely experience problems and may not work.
25+
- [Docker](https://docs.docker.com/engine/install/): Subscribe to Docker Hub and pulldown the latest image from: https://hub.docker.com/_/marklogic
26+
```sh
27+
# Something similar to this, with the latest version tag, which can be found on the dockerhub link above
28+
docker pull store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4
29+
```
30+
- [KubeCTL](https://kubernetes.io/docs/tasks/tools/): Download and install this tool to assist with debugging in a Kubernetes environment.
31+
- [Helm](https://helm.sh/docs/intro/install/): Clone or download the chart repository: https://github.com/marklogic/marklogic-kubernetes
32+
- [Minikube](https://k8s-docs.netlify.app/en/docs/tasks/tools/install-minikube/): Download the Minikube Kubernetes environment, which will host the MarkLogic Server applications.
33+
- Browser: The latest version of a supported web browser. See the list here: [Web Browser](https://developer.marklogic.com/products/support-matrix/)
34+
35+
36+
# Procedure
37+
This section describes the procedure for setting up Minikube, installing MarkLogic Server, and verifying the installation.
38+
39+
40+
## Setting Up Minikube
41+
First you will need to set up the Kubernetes control plane on your local machine. Minikube is a tool that makes it easy to set up a local Kubernetes enviornment.
42+
43+
- Start Minikube: `minikube start --driver=docker`
44+
45+
To verify the Minikube started correctly, use the Kubernetes command line tool, KubeCTL:
46+
47+
```sh
48+
kubectl get nodes
49+
```
50+
```
51+
Expected Output:
52+
NAME STATUS ROLES AGE VERSION
53+
minikube Ready control-plane,master 1d v1.23.3
54+
```
55+
56+
To enable addons run the follow Minikube command for ingress:
57+
`minikube addons enable ingress`
58+
## Installing a Single MarkLogic Host to Minikube
59+
- Push the image used for MarkLogic Server to the VM:
60+
`minikube image load store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4`
61+
The image ID used in the example is `store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4`, which may not be the latest image. To find the latest ID go to https://hub.docker.com/_/marklogic
62+
- Add the helm repository
63+
`helm repo add marklogic https://github.com/marklogic/marklogic-kubernetes`
64+
Additionally create a `values.yaml` file for your installation, like the one found in the repository under `/charts`: https://github.com/marklogic/marklogic-kubernetes/. The `values.yaml` file controls configuration for MarkLogic Server running in kubernetes.
65+
Run `helm install RELEASE_NAME marklogic/marklogic --version=1.0.0-ea1 -f values.yaml` where the `RELEASE_NAME` can be any name you want to use to identify this deployment.
66+
For example: `helm install marklogic-local-dev-env marklogic/marklogic --version=1.0.0-ea1 -f values.yaml`
67+
## Installing Multiple MarkLogic Hosts to Minikube
68+
To create a MarkLogic cluster in Minikube, change the `replicaCount` in the `values.yaml` file to 3, or any other odd number to avoid the [split brain problem](https://help.marklogic.com/Knowledgebase/Article/View/119/0/start-up-quorum-and-forest-level-failover). Then follow the procedure outlined in the [Installing a Single MarkLogic Host to Minikube](##Installing-a-Single-MarkLogic-Host-to-Minikube) section.
69+
70+
## Verifying the Installation
71+
- After the installation is complete, verify the status of the deployment to the cluster with this command:
72+
```sh
73+
kubectl get pods --watch
74+
```
75+
and wait for the following output:
76+
```
77+
marklogic-0 1/1 Running 0 55s
78+
```
79+
This process may take a minute or two.
80+
81+
- You will need to port forward requests to the cluster in order to access MarkLogic Server from `localhost`. Port forwarding can be achieved with the following command:
82+
```sh
83+
kubectl port-forward marklogic-0 8001 8000 7997
84+
```
85+
If you want to forward other ports, just append them to the command separated by a space.
86+
For example:
87+
88+
```sh
89+
kubectl port-forward marklogic-0 8001 8000 7997 7996 7888 1234 1337
90+
```
91+
92+
93+
- To complete this step, access your browser and navigate to `localhost:8001`. You should see the MarkLogic Server Admin interface.
94+
If you are unable to see the MarkLogic Server Admin interface, see the [Debugging](#Debugging) section to gather more information about the cluster and potential errors.
95+
96+
- See the [Cleanup](#Cleanup) section in order to teardown the cluster when you are finished.
97+
98+
# Debugging
99+
This Debugging section contains useful commands to help debug a Kubernetes cluster running MarkLogic Server. Additional information and commands can be found here: https://kubernetes.io/docs/tasks/debug-application-cluster/debug-running-pod/
100+
101+
This command provides additional information about the state of each pod in the cluster.
102+
103+
```sh
104+
kubectl describe pods
105+
```
106+
The command outputs a large amount of data and contains a lot of information. Pay attention to the events section near the bottom of the output to view the state of events, and what occurred during the startup of the pod.
107+
For Example:
108+
109+
```
110+
...
111+
Events:
112+
Type Reason Age From Message
113+
---- ------ ---- ---- -------
114+
Normal Scheduled 13m default-scheduler Successfully assigned default/marklogic-0 to minikube
115+
Normal Pulled 13m kubelet Container image "store/marklogicdb/marklogic-server:10.0-8.3-centos-1.0.0-ea3" already present on machine
116+
Normal Created 13m kubelet Created container marklogic
117+
Normal Started 13m kubelet Started container marklogic
118+
Warning Unhealthy 13m kubelet Startup probe failed: ls: cannot access /var/opt/MarkLogic/ready: No such file or directory
119+
```
120+
**Note:** It is OK that the startup probe failed once. The probe will poll a few times.
121+
122+
-----
123+
124+
Run the following command to see the logs for a specific pod:
125+
```sh
126+
kubectl logs {POD_NAME}
127+
```
128+
The `{POD_NAME}` can be found with the `kubectl get pods` command.
129+
130+
Example output:
131+
132+
```
133+
2022-03-28 16:53:00.127 Info: Memory 4% phys=5812 size=536(9%) rss=275(4%) anon=205(3%) file=9(0%) forest=853(14%) cache=1920(33%) registry=1(0%)
134+
2022-03-28 16:54:01.630 Info: Merging 1 MB from /var/opt/MarkLogic/Forests/Security/00000002 to /var/opt/MarkLogic/Forests/Security/00000003, timestamp=16484858400268930
135+
2022-03-28 16:54:01.657 Info: Merged 1 MB at 37 MB/sec to /var/opt/MarkLogic/Forests/Security/00000003
136+
2022-03-28 16:54:04.155 Info: Deleted 2 MB at 1314 MB/sec /var/opt/MarkLogic/Forests/Security/00000002
137+
```
138+
139+
-----
140+
141+
Run the following command to see the logs for a specific pod :
142+
143+
```sh
144+
kubectl exec -it {POD_NAME} -- /bin/bash
145+
```
146+
The `{POD_NAME}` can be found with the `kubectl get pods` command.
147+
148+
For example:
149+
```sh
150+
> kubectl exec -it marklogic-0 -- /bin/bash
151+
[marklogic_user@marklogic-0 /]$
152+
```
153+
154+
# Cleanup
155+
To cleanup a running kubernetes cluster, run the following commands:
156+
- `helm uninstall <deployment_name>`
157+
For Example:
158+
`helm uninstall marklogic-local-dev-env`
159+
- `minikube delete`
160+
161+

0 commit comments

Comments
 (0)