From 507519cd0e403131278c3d0d6881627674ac78b6 Mon Sep 17 00:00:00 2001
From: Curtis Vogt <curtis.vogt@gmail.com>
Date: Tue, 5 Mar 2024 14:32:15 -0600
Subject: [PATCH] Add quickstart guide

---
 docs/make.jl                     |  1 +
 docs/src/graceful_termination.md | 31 ++++++++++++++-
 docs/src/quickstart.md           | 66 ++++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/quickstart.md

diff --git a/docs/make.jl b/docs/make.jl
index 5708d95..040578f 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -2,6 +2,7 @@ using K8sDeputy
 using Documenter
 
 pages = ["Home" => "index.md",
+         "Quickstart" => "quickstart.md",
          "Health Checks" => "health_checks.md",
          "Graceful Termination" => "graceful_termination.md",
          "API" => "api.md"]
diff --git a/docs/src/graceful_termination.md b/docs/src/graceful_termination.md
index f498bf6..0ecf8bb 100644
--- a/docs/src/graceful_termination.md
+++ b/docs/src/graceful_termination.md
@@ -57,7 +57,7 @@ spec:
         preStop:
           exec:
             command: ["julia", "-e", "using K8sDeputy; graceful_terminate()"]
-      # terminationGracePeriodSeconds: 30
+  # terminationGracePeriodSeconds: 30
 ```
 
 !!! note
@@ -66,3 +66,32 @@ spec:
 
 Finally, the entrypoint for the container should also not directly use the Julia as [init](https://en.wikipedia.org/wiki/Init) process (PID 1). Instead, users should define their entrypoint similarly to
 `["/bin/sh", "-c", "julia entrypoint.jl; sleep 1"]` as this allows the both the Julia process and the `preStop` process to cleanly terminate.
+
+### Read-only Filesystem
+
+If you a read-only filesystem on your container you'll need to configure a writeable volume mount for K8sDeputy.jl. The `DEPUTY_IPC_DIR` environmental variable can be used to instruct K8sDeputy.jl where to store the named pipes it creates for interprocess communication:
+
+```yaml
+apiVersion: v1
+kind: Pod
+spec:
+  containers:
+    - name: app
+      # command: ["/bin/sh", "-c", "julia entrypoint.jl; sleep 1"]
+      env:
+        - name: DEPUTY_IPC_DIR
+          value: /mnt/deputy-ipc
+      lifecycle:
+        preStop:
+          exec:
+            command: ["julia", "-e", "using K8sDeputy; graceful_terminate()"]
+      securityContext:
+        readOnlyRootFilesystem: true
+      volumeMounts:
+        - mountPath: /mnt/deputy-ipc
+          name: deputy-ipc
+  volumes:
+    - name: deputy-ipc
+      emptyDir:
+        medium: Memory
+```
diff --git a/docs/src/quickstart.md b/docs/src/quickstart.md
new file mode 100644
index 0000000..a8b3e45
--- /dev/null
+++ b/docs/src/quickstart.md
@@ -0,0 +1,66 @@
+# Quickstart
+
+For users who want to get started quickly you can use the following template to incorporate liveness probes, readiness probes, graceful termination, binding to non-priviledged ports, and read-only filesystem support.
+
+1. Add K8sDeputy.jl to your Julia project: `Pkg.add("K8sDeputy")`
+2. Define the following `entrypoint.jl` in your application and include it in the `WORKDIR` of your `Dockerfile`:
+
+   ```julia
+   using K8sDeputy
+   deputy = Deputy()
+   server = K8sDeputy.serve!(deputy, "0.0.0.0")
+   graceful_terminator(() -> shutdown(deputy))
+   
+   # Application initialization code
+   
+   readied(deputy)
+   
+   # Application code
+   ```
+
+3. Incorporate the following changes into your K8s resource manifest:
+
+   ```yaml
+   apiVersion: v1
+   kind: Pod
+   spec:
+     containers:
+       - name: app
+         command: ["/bin/sh", "-c", "julia entrypoint.jl; sleep 1"]
+         env:
+           - name: DEPUTY_HEALTH_CHECK_PORT
+             value: "44444"
+           - name: DEPUTY_IPC_DIR
+             value: /mnt/deputy-ipc
+         ports:
+           - name: health-check
+             containerPort: 44444  # Must match ENV `DEPUTY_HEALTH_CHECK_PORT`
+             protocol: TCP
+         livenessProbe:
+           httpGet:
+             path: /health/live
+             port: health-check
+           timeoutSeconds: 5
+         readinessProbe:
+           httpGet:
+             path: /health/ready
+             port: health-check
+           timeoutSeconds: 5
+         lifecycle:
+           preStop:
+             exec:
+               command: ["julia", "-e", "using K8sDeputy; graceful_terminate()"]
+         securityContext:
+           capabilities:
+             drop:
+               - all
+           readOnlyRootFilesystem: true
+         volumeMounts:
+           - mountPath: /mnt/deputy-ipc
+             name: deputy-ipc
+     terminationGracePeriodSeconds: 30
+     volumes:
+       - name: deputy-ipc
+         emptyDir:
+           medium: Memory
+   ```