builds

Being an emacs (specifically spcaemacs) user, I take most of my notes in org mode and prefer the workflow of org mode to markdown. It allows me to more easily get information out of my head, and organize it in a structured, easy to navigate format, not only on this site, but in plain text as well. However, docsify does not come with native org file support, so something had to be done.

# buid.sh
find . -name \*.org -print0 | xargs -0 -I{} echo {} | sed 's/org//g' > files.txt
while read line; do
pandoc -s ${line}org -o ${line}md --to=markdown-fenced_code_attributes
done < ./files.txt

build.sh is a simple script that takes all of the org files in the project, and converts them into markdown files of the same name. --to=markdown-fenced_code_attributes is included so that org-mode code blocks are converted into markdown code blocks that are compatible with docsify.js.

The build process takes place in Gitlab's CI/CD pipeline when creating the docker image.

FROM  jagregory/pandoc as builder
RUN mkdir /app
# Set the working directory to /music_service
WORKDIR /app
# Copy the current directory contents into the container at /music_service
ADD . /app
RUN ls
RUN ./build.sh

FROM nginx
COPY --from=builder ./app/docs /usr/share/nginx/html

using an intermediate image to build the site and nginx to serve it makes sure that the final image size is small.

merges to the master branch triggers a deploy pipeline, which send my newly created docker image to my kubernetes cluster (which resides in my living room) with the tag name of the image being the short sha of the commit that triggered the build. This allows me to easily identify which commits are causing errors, and easy rollbacks to previously known working states.

I don't have the concept of tags creating deploys for this project simply because the idea behind this site is the ability to quickly add an update information to it, so that I have access to it anywhere.

Manual processes

as much as I would like to automate every proccess of updating this site, there are some manual processes left. Currently links on the sidebar must be manually added and removed, however, the formatting of the links is similar to the directory structure of the project, so one day build.sh may be expanded to create a generated _sidebar.html

project directory structure

rob@ThinkPad-T440s:~/grimeywebsites.com/docs (pandoc)*
λ date
Mon Mar 25 03:06:35 CDT 2019
rob@ThinkPad-T440s:~/grimeywebsites.com/docs (pandoc)*
λ tree
.
├── bookmarks
│   ├── images
│   │   ├── Grahams_Hierarchy_of_Disagreement.png
│   │   ├── is_it_worth_the_time.png
│   │   ├── service-reliablilty-heirarchy.jpg
│   │   └── what_graph_should_i_use.jpg
│   ├── images.md
│   └── links.md
├── docs
│   ├── quick-search
│   │   └── README.md
│   └── README.md
├── ergonomics
│   ├── emacs.md
│   ├── keyboard-shortcuts.md
│   └── xset.md
├── index.html
├── meta
│   └── README.org
├── _navbar.md
├── nutrition
│   └── README.md
├── quotes
│   ├── crowley.md
│   ├── marcus-aurelius.md
│   ├── misc.md
│   └── quotes.md
├── README.org
├── resume
│   └── README.md
├── _sidebar.md
└── snippets
    ├── electron.md
    ├── kubernetes
    │   ├── resource-definitions.md
    │   └── setup
    │       ├── auto-completion.md
    │       ├── cleanup.md
    │       ├── deployments.md
    │       ├── initial.md
    │       ├── master-node.md
    │       ├── README.md
    │       └── worker-node.md
    ├── kubernetes.md
    ├── letsencrypt.md
    ├── networking.md
    ├── openwrt.md
    ├── rails.md
    └── README.md

12 directories, 37 files

_sidebar.md

- Bookmarks
  - [Links](bookmarks/links)
  - [Images](bookmarks/images)
- Documentation
  - [Quick Search](/docs/quick-search/)
- Ergonomics
  - [Emacs](/ergonomics/emacs.md)
  - [Keyboard Shortcuts](/ergonomics/keyboard-shortcuts.md)
  - [Xset](/ergonomics/xset.md)
- Snippets
  - Kubernetes
    - [Bare Metal Setup](/snippets/kubernetes/setup/)
      - [Initial](/snippets/kubernetes/setup/initial.md)
      - [Master Node](/snippets/kubernetes/setup/master-node.md)
      - [Worker Node](/snippets/kubernetes/setup/worker-node.md)
      - [Auto Complete](/snippets/kubernetes/setup/auto-completion.md)
      - [Deployments](/snippets/kubernetes/setup/deployments.md)
      - [Cleanup](/snippets/kubernetes/setup/cleanup.md)
    - [Resource Definitions](/snippets/kubernetes/resource-definitions.md)
  - [Electron](/snippets/electron.md)
  - [LetsEncrypt](/snippets/letsencrypt.md)
  - [OpenWrt](/snippets/openwrt.md)
  - [Rails](/snippets/rails.md)
  - [Networking](/snippets/networking.md)
- Quotes
  - [Aleistor Crowley](/quotes/crowley.md)
  - [Marcus Aurelius](/quotes/marcus-aurelius.md)
  - [Misc](/quotes/misc.md)
- [Nutrition](/nutrition/)
- [Meta](/meta/)

There is not a set practice I have yet for laying out the order of links and directories yet, but `org-mode` supports custom properties which could be used to generate the order in which entries should be displayed.

local development and testing

previewing the site locally is done using docker-compose. Previously simply running an http server in the ./docs directory was sufficient, but the addition of build.sh has made it so that the site must be generated from org files to be previewed. Rather than running that command locally, and polluting my work space with generated markdown, docker-compose offers a seamless way to preview the site locally when making major changes. The image created from the docker-compose.yml is also an exact copy of my production environment, which allows greater confidence when making major changes.

docker-compose.yml

version: '3.7'

services:
  web:
    build: .
    ports:
      - 8000:80

A setback to using this method is that I do not have the capability to hot reload on changes, and building the image takes many second when running docker-compose up --build (approx. 10 seconds on my laptop). Seeing changes also requires a full build to take place, since building the markdown happens in docker. Most changes to this site do not require physically viewing the site due to the generative nature, therefore revising this processes is a low priority.