You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Local_Development_Tutorial.md
+50-38Lines changed: 50 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,37 +11,42 @@
11
11
*[Cleanup](#Cleanup)
12
12
13
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
14
+
This tutorial describes how to set up local Kubernetes development environment with Minikube and MarkLogic Server. It covers these tasks:
15
+
-Set up the prerequisites necessary for local development using MarkLogic Server in Kubernetes
16
+
- How to run Minikube and load MarkLogic Server into the Kubernetes cluster
17
+
- Access the MarkLogic Server cluster
18
+
- How to Debug the Kubernetes environment
19
+
- How to Clean up your environment
20
20
21
21
22
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
23
+
The following steps assume you are running this tutorial from a desktop environment. Mobile environments will likely experience problems and may not work.
- If running in Linux: `minikube start --driver=docker`
44
-
To verify the minikube started correctly run the following command:
43
+
44
+
## Setting Up Minikube
45
+
First we need to setup the Kubernetes control plane on our local machine, Minikube is an easy tool which handles setting up a Kubernetes enviornment locally.
- If you are running in a Linux OS: `minikube start --driver=docker`
49
+
To verify the minikube started correctly we can use the Kubernetes command line tool, KubeCTL:
45
50
```sh
46
51
kubectl get nodes
47
52
```
@@ -51,53 +56,59 @@ NAME STATUS ROLES AGE VERSION
51
56
minikube Ready control-plane,master 1d v1.23.3
52
57
```
53
58
54
-
- Enable Addons: `minikube addons enable ingress` for ingress
59
+
- Enable Addons: `minikube addons enable ingress` for ingress.
55
60
## 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`
61
+
- Push the image used for MarkLogic Server to the VM: `minikube image load store/marklogicdb/marklogic-server:10.0-9-centos-1.0.0-ea4`
57
62
- 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`
63
+
- Navigate to where you downloaded or cloned the MarkLogic Helm repository.
64
+
- Verify that the image loaded to Minikube with the comand above matches the `repository` and `tag` in the `values.yaml`.
60
65
```YAML
61
66
image:
62
67
repository: store/marklogicdb/marklogic-server
63
68
tag: 10.0-9-centos-1.0.0-ea4
64
69
```
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 .`
70
+
- Navigate to the `/charts` folder in your local directory.
71
+
- Run `helm install RELEASE_NAME .` where the `RELEASE_NAME` can be any name you want to use to identify this deployment. For example: `helm install marklogic-local-dev-env .`.
67
72
## Installing Multiple MarkLogic Hosts to Minikube
68
73
TODO
69
74
70
75
## Verifying the Installation
71
-
- After the installation, verify the status of the deployment to the cluster with:
76
+
- After the installation is complete, verify the status of the deployment to the cluster with this command:
72
77
```sh
73
78
kubectl get pods --watch
74
79
```
75
80
and wait for the following output:
76
81
```
77
82
marklogic-0 1/1 Running 0 55s
78
83
```
79
-
It may take a minute or two.
84
+
This process may take a minute or two.
80
85
81
-
- Port forward requests to the cluster in order to access it from `localhost` with the following command:
86
+
- 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
87
```sh
83
88
kubectl port-forward marklogic-0 8001 8000 7997
84
89
```
85
-
- If you want to forward other ports just append them to the command separated by a space
90
+
If you want to forward other ports just append them to the command separated by a space
- Finally access your browser and navigate to `localhost:8001` and you should see the MarkLogic Server Admin Interface
88
-
- If you're unable to see the MarkLogic Server Admin Interface interface proceed to the debugging section to gather more information on the cluster and potential errors.
98
+
- To complete this step, access your browser and navigate to `localhost:8001`. You should see the MarkLogic Server Admin interface.
99
+
If you are unable to see the MarkLogic Server Admin Interface, see the Debugging section to gather more information about the cluster and potential errors.
89
100
90
-
- Proceed to the [Cleanup](##Cleanup) section in order to teardown the cluster when finished
101
+
- When you are finished, see the [Cleanup](##Cleanup) section in order to teardown the cluster when finished
91
102
92
103
# 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/
104
+
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/
94
105
95
-
The below command gives additional information on the state of each pod in a cluster
106
+
This command provides additional information about the state of each pod in the cluster.
96
107
97
108
```sh
98
109
kubectl describe pods
99
110
```
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 occurred during the startup of the pod.
111
+
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.
101
112
EX:
102
113
103
114
```
@@ -111,11 +122,11 @@ Events:
111
122
Normal Started 13m kubelet Started container marklogic
112
123
Warning Unhealthy 13m kubelet Startup probe failed: ls: cannot access /var/opt/MarkLogic/ready: No such file or directory
113
124
```
114
-
Note here it's ok that the startup probe failed once, the probe will poll a few times.
125
+
**Note:** It is OK that the startup probe failed once. The probe will poll a few times.
115
126
116
127
-----
117
128
118
-
To get the logs on a pod run the following:
129
+
Run the following command to see the logs on a specific pod:
119
130
```sh
120
131
kubectl logs {POD_NAME}
121
132
```
@@ -132,22 +143,23 @@ Example Output:
132
143
133
144
-----
134
145
135
-
To get local access to a pod you can run the following:
146
+
Run the following command to see the logs on a specific pod :
0 commit comments