add content/articles/site-backend.md (draft)

1 files changed, 178 insertions, 0 deletions

diff --git a/content/articles/site-backend.md b/content/articles/site-backend.md
new file mode 100644
index 0000000..6bfa592
--- /dev/null
+++ b/content/articles/site-backend.md
@@ -0,0 +1,178 @@
+---
+slug: "site-backend"
+title: "Site Backend"
+
+# date (optional for articles)
+date: "2023-09-08T05:07:47-04:00"
+
+# draft articles are not visible on live site
+draft: true
+
+# show on articles page
+show: true
+
+# uncomment to show table of contents
+toc: true
+---
+## Overview
+
+This site is statically generated by [Hugo][] and themed with a
+stripped-down version of [Bulma][].  Both have been heavily customized;
+see the [Configuration](#configuration) section for details.
+
+The goals of this setup are:
+
+- Size
+- Speed
+- Security
+- Mobile Support
+- Accessibility
+- Simplicity (for me)
+
+## History
+
+From 1998 to 2019 this site was generated by a custom [PHP][] backend,
+written by me.  In 2019 I resurrected the site after a several year
+hiatus and migrated the site from the custom [PHP][] backend to
+[Jekyll][].  In 2021 I switched from [Jekyll][] to [Hugo][].
+
+## Content
+
+### HTML
+
+I create and edit site content with [vim][] in [Markdown][] format and
+preview the results locally with `hugo serve -D ...`.  Articles and blog
+posts are saved as drafts and committed to the [Git][] repository so I
+can work on them as time permits.
+
+The content and site layout is designed with accessibility and mobile in
+mind.  This means:
+
+- links, and table components have `title`, `aria-label` attributes
+- images have captions, fallback formats, `title` and `alt` attributes.
+- images scale gracefully to thumbnails on mobile
+- the site honors users' [color scheme preference][] and has a manual
+  theme override
+- The page menu bar collapes to a hamburger menu on mobile.
+
+### Images
+
+Images are created as follows:
+
+- Mathematical content is created using [Mathy][], saved as [SVG][],
+  and minified using [minify][].
+- Charts are created with [Matplotlib][], saved as [SVG][], and minified
+  using [minify][].
+- Lossless images (e.g. screenshots) are scaled and cropped with
+  [GraphicsMagick][] and served as a lossless [WebP][]
+  with a [PNG][] fallback.  The fallback is compressed with
+  [pngquant][].
+- Lossy images are [GraphicsMagick][] and served as a lossy [WebP][]
+  with a [JPEG][] fallback.
+- Menubar icons are borrowed from [Bootstrap Icons][].
+- The animated site logo is generated by [this Ruby script][logo-script].
+
+### JavaScript
+
+There is almost no [JavaScript][], by design.  The one script that is
+used is minimal, [deferred][], used for two things:
+
+1. to handle the [theme toggle][].
+2. to toggle the mobile site menu.
+
+## Deployment
+
+Once I am ready to apply any outstanding changes to the public web site,
+I push the outstanding commits to a remote [Git][] repository. This
+triggers a [`post-receive` hook][], which sends an authenticated `POST`
+request to a [web hook][] exposed on a TLS endpoint on the web server.
+
+The [web hook][] runs a [deployment script (`deploy.rb`)][] which does
+the following:
+
+1. Verifies the authenticated timestamp (to prevent replay attacks).
+2. Clones the upstream repository.
+3. Executes [Hugo][] (`hugo --minify -d ...`) to build the site minified
+   in a unique output directory.
+4. Updates the `htdocs` symlink for the public web site to point at
+   the output directory from the previous step.
+5. Removes any stale builds.
+
+## Configuration
+
+This section discusses the configuration for [Hugo][], [Bulma][] and
+[Apache][].
+
+### Hugo Configuration
+
+[Hugo][] is configured to use [Chroma syntax higlighting][] with inline
+styles disabled (e.g., `class` attributes only, no `style`) in order to
+support the restrictive `Content-Security-Policy` header (see "HTTP
+Headers").
+
+The formatted tables in the pages site are generated via [my
+`hugo-shortcode-table` shortcode][], because the native table generator
+for [Hugo][] uses inline styles.
+
+I have also written a couple of custom [shortcodes][] to generate
+`<picture>` and `<figure>` elements in order to support [progressive
+enhancement][].
+
+The generated [HTML][] has been modified to:
+
+- add support `go-import` 
+- add a [Mastodon][] `<link rel='me' ...>` tag.
+- remove all unnecessary tags 
+- to combine and [minify][] and [JavaScript][] and [CSS][] assets.
+- to add `integrity` attributes to `<link>` and `<script>` tags.
+
+### Bulma Configuration
+
+**TODO:**
+
+- bulma modified to remove all unnecessary components
+  - show `style.css`
+- added chroma styles
+- added dark mode
+
+### Apache Configuration
+
+**TODO:**
+
+- security headers (see next section)
+- `static/files/articles/site-backend/pablotron.org.conf.txt` (config w/ garbage removed)
+- mod deflate
+- mod rewrite for old links
+- aggressive caching
+- http2
+- letsencrypt
+- tls config (1.2 or newer, remove garbage algos)
+
+## HTTP Security Headers
+
+TODO
+
+## Validation
+
+I periodically verify the following manually:
+
+- Developer console: Page load time, cached and uncached page size.
+- [Lighthouse][]: Accessibility, desktop score, and mobile score.
+- security headers
+- tls configuration
+- manual verification in the desktop and mobile versions of chrome and
+  firefox
+
+## Other
+
+- content served minified, cached, and compressed.
+(more stuff from `TODO.md`)
+
+```apache
+# TODO: include annotated files/articles/site-backend/pablotron.org.conf.txt
+```
+
+[hugo]: https://gohugo.io/
+  "Hugo static site generator."
+[bulma]: https://bulma.io/
+  "Bulma minimal CSS framework."