Browse Source

updated README more

Josh Habdas 7 months ago
parent
commit
2dd51623c4
1 changed files with 45 additions and 23 deletions
  1. 45
    23
      README.md

+ 45
- 23
README.md View File

@@ -1,30 +1,53 @@
1 1
 
2
-# After-Dark on k3s  
2
+# After Dark K3s
3 3
 
4
-## [... a lightweight Kubernetes by Rancher](https://k3s.io/)
4
+> Run [After Dark](https://after-dark.habd.as) in a lightweight [K3s](https://k3s.io/) cluster providing the power of [Kubernetes](https://kubernetes.io/) container orchestration for a fraction of the resources.
5 5
 
6
-## Install K3s on your host  
6
+## Installation
7 7
 
8
-``$ curl -sfL https://get.k3s.io | sh -``
9
-Check for Ready node, takes maybe 30 seconds  
10
-``$ kubectl get node``  
8
+In two steps. First setup k3s, then deploy After Dark to your cluster.
11 9
 
12
-## Deploy After-Dark  
10
+### Step 1: Download and install k3s via script
13 11
 
14
-Download deployment files on your host:  
15
-``$ git clone https://git.habd.as/teowood/after-dark-k3s-amd64.git``  
16
-Apply deployment files:  
17
-``$ cd after-dark-k3s-amd64`` then ``$ kubectl apply -f .``  
12
+Download and install k3s [via script](https://get.k3s.io) as suggested on the [K3s website](https://k3s.io/):
18 13
 
19
-## Basic explanation of deployment
14
+```sh
15
+curl -sfL https://get.k3s.io | sh -
16
+# Check for Ready node, takes maybe 30 seconds
17
+kubectl get node
18
+```
20 19
 
21
-This is a multi tier deployment:  
20
+Run on host machine you wish to use to manage your cluster. This could be locally for development, on an [RPi](https://raspberrypi.org/) or even a VPS with 512 MB RAM. The K3s installation script gives you access to the [`kubectl` command](https://kubernetes.io/docs/reference/kubectl/overview/) giving you the ability to perform container orchestration straight-away.
22 21
 
23
-* ``after-dark-k3s-hugo.yaml`` deploys a pod with two containers. First an  init container which downloads the after-dark repository and finally the actual hugo container which kicks in and installs the site. When done it fires hugo in watch mode.  
24
-* ``after-dark-nginx.yaml`` deploys an nginx server that servers our rendered site.
25
-* ``after-dark-service.yaml`` exposes our nginx to a nodeport so we can actually reach the site.
22
+### Step 2: Deploy After Dark to your k3s cluster
26 23
 
27
-## Operate your k3s after-dark site  
24
+Pull down [Deployment](https://kubernetes.io/docs/concepts/) files to host machine:
25
+
26
+```sh
27
+git clone https://git.habd.as/teowood/after-dark-k3s-amd64
28
+```
29
+
30
+Use [`kubectl`](https://kubernetes.io/docs/reference/kubectl/overview/) to apply the deployment files and get things kicked off:
31
+
32
+```sh
33
+cd after-dark-k3s-amd64 && kubectl apply -f .
34
+```
35
+
36
+Your cluster is now running and you have a containerized version of [After Dark](https://after-dark.habd.as) running inside your cluster and accessible via browser.
37
+
38
+Continue reading for an overview of the deployment and basic usage.
39
+
40
+## Overview of deployment
41
+
42
+Multi-tier deployment consisting of:  
43
+
44
+* ``after-dark-k3s-hugo.yaml`` deploys a pod using two containers. First, an ephemeral initialization tasked with downloading After Dark from [source repo](https://git.habd.as/comfusion/after-dark) and, finally, the actual hugo container which kicks in and installs the site. When done it runs [`hugo server`](https://gohugo.io/commands/hugo_server/) in _watch mode_ so [Hugo](https://gohugo.io/) rebuilds After Dark site as files change.
45
+* ``after-dark-nginx.yaml`` deploys an [nginx](https://www.nginx.com/) web server that serves the content of the rendered site. As file changes occur Hugo will rebuild the After Dark site and nginx will pick up the changes.
46
+* ``after-dark-service.yaml`` exposes nginx to a [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) so we can actually reach the site from a browser.
47
+
48
+## Usage
49
+
50
+### Operating your k3s After Dark site  
28 51
 
29 52
 * First retrieve your pod name and store it in a variable for your convenience ``$ AD_POD=$(kubectl get pods -l app=after-dark-hugo -o jsonpath='{.items[0].metadata.name}')``  
30 53
 * Create a new post  
@@ -36,13 +59,12 @@ This is a multi tier deployment:
36 59
 * Full rebuilt your site e.g after new styles appied ``$ kubectl exec  $AD_POD -- hugo -c /my-content -d /output`` Note this will also revert drafts.  
37 60
 * Edit your posts ``$ kubectl exec -it $AD_POD -- vi /my-content/my-post.md`` or directly inside your host's ``/my-content``
38 61
 
39
-## Browse to your site  
62
+### Browsing to your site  
40 63
 
41
-Locate the nodeport we exposed our nginx for after-dark  
42
-``$ kubectl get svc``
43
-The port we are looking for is the the one next to ``8080:``
44
-For instance in the example below, you would point your browser to `http://your-node-IP:32146`. Ignore the Cluster-IP and the External-IP shown below, you want the real IP of your host.
64
+To view your site run `kubectl get svc` to locate the NodePort exposed to nginx. You should see output like:
45 65
 
46 66
 | Name | Type | Cluster-IP | External-IP | Port(s) | Age |
47 67
 |--------------------|----------|---------------|-------------|----------------|-----|
48
-| after-dark-service | NodePort | 10.43.129.249 | `<none>` | 8080:32146/TCP | 1h |  
68
+| after-dark-service | NodePort | 10.43.129.249 | `<none>` | 8080:32146/TCP | 1h |
69
+
70
+Grab the port number next to `8080:` and use it to browse to your site using the node IP or, locally on the host, using the loopback e.g. `http://localhost:32146`. (Note: Ignore the <samp>Cluster-IP</samp> and the <samp>External-IP</samp>, you want the real IP of your host.)

Loading…
Cancel
Save