Skip to content

Commit 09c0c69

Browse files
Daniel WasserlaufDaniel Wasserlauf
Daniel Wasserlauf
authored and
Daniel Wasserlauf
committed
feature/cld-421: added docs folder and tutorial draft for getting started in k8s
1 parent 7dabed2 commit 09c0c69

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎docs/Local_Development_Tutorial.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Local Development Tutorial: Getting Started with Kubernetes in MarkLogic
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+
* [Verifying the Installation](##Verifying-the-Installation)
10+
* [Debugging](#Debugging)
11+
* [Cleanup](#Cleanup)
12+
13+
# Introduction
14+
This tutorial serves as a guide for local development setup with Minikube and MarkLogic. These tasks are covered in this guild:
15+
- Setting up the necessary prerequisites for local MarkLogic in Kubernetes development
16+
- How to run Minikube and load MarkLogic into the cluster
17+
- How to Access the MarkLogic cluster
18+
- How to Debug the environment
19+
- How to Clean up
20+
21+
22+
## Prerequisites
23+
The following assumes you are running this tutorial from a desktop environment, mobile environments will likely experience problems and may not work
24+
- [Docker](https://docs.docker.com/engine/install/)
25+
-- Subscribe 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/)
31+
- [HELM](https://helm.sh/docs/intro/install/)
32+
-- Clone or download the chart repository: https://github.com/marklogic/marklogic-kubernetes
33+
- [Minikube](https://k8s-docs.netlify.app/en/docs/tasks/tools/install-minikube/)
34+
- If running on Mac OSX: [Virtual Box](https://www.virtualbox.org/)
35+
- A supported [Web Browser](https://developer.marklogic.com/products/support-matrix/)
36+
37+
38+
# Procedure
39+
Below is the procedure for setting up Minikube, installing MarkLogic, and verifying the installation.
40+
41+
## Setting Up minikube
42+
- Start minikube: `minikube start --driver=virtualbox`
43+
-- If running in Linux: `minikube start --driver=docker`
44+
To verify the minikube started correctly run the following command:
45+
```sh
46+
kubectl get nodes
47+
```
48+
```
49+
Expected Output:
50+
NAME STATUS ROLES AGE VERSION
51+
minikube Ready control-plane,master 1d v1.23.3
52+
```
53+
54+
- Enable Addons: `minikube addons enable ingress` for ingress
55+
## Installing a Single MarkLogic Host to minikube
56+
- Push the image used for ML to the VM: `minikube image load store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4`
57+
-- The above Image ID: `store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4` is whatever the latest image is, to find the latest id go to https://hub.docker.com/_/marklogic
58+
- Navigate to where you downloaded or cloned the MarkLogic helm repository
59+
-- Verify the image loaded to minikube above matches the `repository` and `tag` in the `values.yaml`
60+
```YAML
61+
image:
62+
repository: store/marklogicdb/marklogic-server
63+
tag: 10.0-9-centos-1.0.0-ea4
64+
```
65+
-- Navigate to the `/charts` folder
66+
-- Run `helm install RELEASE_NAME .` Where the `RELEASE_NAME` can be anything you want to identify this deployment EX: `helm install marklogic-local-dev-env .`
67+
## Installing Multiple MarkLogic Hosts to Minikube
68+
TODO
69+
70+
## Verifying the Installation
71+
- After the installation, verify the status of the deployment to the cluster with:
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+
It may take a minute or two.
80+
81+
- Port forward requests to the cluster in order to access it from `localhost` 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+
87+
- Finally access your browser and navigate to `localhost:8001` and you should see the MarkLogic Server Admin Interface
88+
-- If your unable to see the MarkLogic Server Admin Interface interface proceed to the debugging section to gather more information on the cluster and potential errors.
89+
90+
- Proceed to the [Cleanup](##Cleanup) section in order to teardown the cluster when finished
91+
92+
# Debugging
93+
The 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/
94+
95+
The below command gives additional information on the state of each pod in a cluster
96+
97+
```sh
98+
kubectl describe pods
99+
```
100+
The output of this command is large and contains a lot of information pay attention to the bottom events section to see the state of events and what occured during the startup of the pod.
101+
EX:
102+
103+
```
104+
...
105+
Events:
106+
Type Reason Age From Message
107+
---- ------ ---- ---- -------
108+
Normal Scheduled 13m default-scheduler Successfully assigned default/marklogic-0 to minikube
109+
Normal Pulled 13m kubelet Container image "store/marklogicdb/marklogic-server:10.0-8.3-centos-1.0.0-ea3" already present on machine
110+
Normal Created 13m kubelet Created container marklogic
111+
Normal Started 13m kubelet Started container marklogic
112+
Warning Unhealthy 13m kubelet Startup probe failed: ls: cannot access /var/opt/MarkLogic/ready: No such file or directory
113+
```
114+
Note here its ok that the startup probe failed once, the probe will poll a few times.
115+
116+
-----
117+
118+
To get the logs on a pod run the following:
119+
```sh
120+
kubectl logs {POD_NAME}
121+
```
122+
The `{POD_NAME}` can be found with the `kubectl get pods` command.
123+
124+
Example Output:
125+
126+
```
127+
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%)
128+
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
129+
2022-03-28 16:54:01.657 Info: Merged 1 MB at 37 MB/sec to /var/opt/MarkLogic/Forests/Security/00000003
130+
2022-03-28 16:54:04.155 Info: Deleted 2 MB at 1314 MB/sec /var/opt/MarkLogic/Forests/Security/00000002
131+
```
132+
133+
-----
134+
135+
To get local access to a pod you can run the following:
136+
137+
```sh
138+
kubectl exec --stdin --tty {POD_NAME} -- /bin/bash
139+
```
140+
The `{POD_NAME}` can be found with the `kubectl get pods` command
141+
142+
EX:
143+
```sh
144+
> kubectl exec --stdin --tty marklogic-0 -- /bin/bash
145+
[marklogic_user@marklogic-0 /]$
146+
```
147+
148+
# Cleanup
149+
To cleanup a running cluster run the following commands
150+
- `helm uninstall <deployment_name>` EX: `helm uninstall marklogic-local-dev-env`
151+
- `minikube delete`
152+
153+

0 commit comments

Comments
 (0)