From dc68c42ce1b8efc1003137c08dd5961b93705684 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Fri, 31 May 2024 03:58:29 -0400 Subject: content/articles/site-backend.md: populate most of the content --- content/articles/site-backend.md | 638 ++++++++++++++++++++++++++++++++++----- 1 file changed, 561 insertions(+), 77 deletions(-) (limited to 'content') diff --git a/content/articles/site-backend.md b/content/articles/site-backend.md index 6bfa592..5fb750b 100644 --- a/content/articles/site-backend.md +++ b/content/articles/site-backend.md @@ -3,7 +3,7 @@ slug: "site-backend" title: "Site Backend" # date (optional for articles) -date: "2023-09-08T05:07:47-04:00" +date: "2024-05-31T03:57:18-04:00" # draft articles are not visible on live site draft: true @@ -13,21 +13,40 @@ show: true # uncomment to show table of contents toc: true + +pics: + editing: + css: "image" + tip: "Editing this article with Vim and Firefox." + sources: + - "/files/articles/site-backend/0-editing-1024.webp" + - src: "/files/articles/site-backend/0-editing-1024.png" + width: 1024 + height: 640 + ssl-labs-report: + css: "image" + tip: "SSL Labs SSL Test results for this site." + sources: + - "/files/articles/site-backend/1-ssl-labs-20240530-1024.webp" + - src: "/files/articles/site-backend/1-ssl-labs-20240530-1024.png" + width: 1024 + height: 525 + securityheaders-report: + css: "image" + tip: "Security headers report for this site from securityheaders.com" + sources: + - "/files/articles/site-backend/2-securityheaders-1024.webp" + - src: "/files/articles/site-backend/2-securityheaders-1024.png" + width: 1024 + height: 320 --- ## 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: +Site content is managed as [Markdown][] files stored in a [Git][] +repository. The theme is a modified version of [Bulma][]. The site is +statically generated by [Hugo][]. -- Size -- Speed -- Security -- Mobile Support -- Accessibility -- Simplicity (for me) +[{{< pe-figure "editing" >}}][editing-this-article] ## History @@ -36,72 +55,375 @@ 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][]. +## Goals + +The goals of this site backend are: + +- Small +- Fast +- Secure +- Mobile-friendly +- Accessible +- Simple (for me) + +Static generation neatly addresses the first three goals: + +- The site is small because the [Hugo][] can be configured to + aggressively pack and minify content and assets. Images are + also compressed and served in multiple formats (see [Hugo + Configuration](#hugo-configurationi "Hugo Configuration") and [Images](#images + "Images")). +- The site is fast because web servers can serve static content + extremely quickly, and because static content can be cached. Caching + and compression are enabled in [Apache][] (see [Apache + Configuration](#apache-configuration "Apache Configuration")). +- The site is secure because the content is static; there is no + web-accessible endpoint which can upload files or modify content. + Additional security measures are discussed in several of the following + sections. + +Explanations of how I keep the site mobile-friendly and accessible are +available in the [HTML](#html "HTML") and [Hugo +Configuration](#hugo-configuration "Hugo Configuration") sections below. + +**TODO:** discuss simplicity + ## Content ### HTML -I create and edit site content with [vim][] in [Markdown][] format and +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: +The content and layout is designed to be accessible and mobile-friendly: -- links, and table components have `title`, `aria-label` attributes -- images have captions, fallback formats, `title` and `alt` attributes. +- links and table components have `title` and `aria-label` attributes +- images have captions, fallback formats, and `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. +- the site supports [dark mode][], checks the [color scheme + preference][prefers-color-scheme] to determine the default theme, + and has a [manual theme switcher][post-theme-switcher] +- The 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. + minified using [minify][], and served cached and compressed by [Apache][]. +- Charts are created with [Matplotlib][], saved as [SVG][], minified + with [minify][], and served cached and compressed by [Apache][] + Example: [This Python script][bench-chart] was used to generate the + bar charts in [this blog post][post-fips203ipd]. +- Lossless raster images (e.g. screenshots) are scaled and cropped with + [GraphicsMagick][] and served as a lossless [WebP][] with a [PNG][] + fallback compressed by [pngquant][]. +- Lossy raster images (e.g. pictures) are scaled and cropped with + [GraphicsMagick][] and served as a lossy [WebP][] with a [JPEG][] + fallback. + +Other notes: + +- The animated site logo is an [SVG][] generated by [this Ruby script][gen-logo.rb]. - Menubar icons are borrowed from [Bootstrap Icons][]. -- The animated site logo is generated by [this Ruby script][logo-script]. +- I reviewed several [PNG][] compressors in [this post][post-png-compressors]. ### 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. +This site has almost no [JavaScript][], by design. The [JavaScript][] +that is used is minimal, [modern][es2015], [deferred][], and only used +for the [theme switcher][post-theme-switcher] and burger menu. + +Below is the unminified `script.js` for this site with some notes +removed. It is 777 bytes minified and 586 bytes minified and +compressed: + +```js +'use strict'; + +// +// script.js - script which handles: +// +// - set theme +// - theme switcher and burger menu event handlers +// + +const D = document, + C = D.body.parentElement.classList, + L = localStorage, + M = window.matchMedia, + on = (el, id, fn) => el.addEventListener(id, fn); + +// use theme if set, otherwise fall back to browser preference +if (L && L.theme && L.theme === 'dark') { + C.add('dark'); // theme set to "dark" +} else if ((!L || !L.theme) && M && M('(prefers-color-scheme: dark)').matches) { + C.add('dark'); // prefers dark color scheme +} + +document.addEventListener('DOMContentLoaded', () => { + // theme toggle event handler + on(D.querySelector('.navbar-item[data-id="theme"]'), 'click', (e) => { + e.preventDefault(); // stop event + L.theme = C.toggle('dark') ? 'dark' : 'light'; // toggle + }); + + // iterate through burgers, bind to click events + D.querySelectorAll('.navbar-burger').forEach(e => on(e, 'click', () => { + // then toggle is-active on burger and menu + [e, D.getElementById(e.dataset.target)].forEach( + e => e.classList.toggle('is-active') + ) + })); +}); +``` +[Download][script.js] ## 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. +triggers a [`post-receive` Git hook][post-receive], which sends an +[HMAC][]-authenticated `POST` request to a [web hook][] endpoint on the +web server. -The [web hook][] runs a [deployment script (`deploy.rb`)][] which does -the following: +The [web hook][] verifies the [HMAC][] and then runs [a deployment +script][deploy.rb] which does the following: -1. Verifies the authenticated timestamp (to prevent replay attacks). +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. +3. Executes [Hugo][] (`hugo --minify -d ...`) to build the site in an + isolated output directory. +4. Updates the `htdocs` symlink for the public-facing 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][]. +This section discusses the configuration for [Apache][], [Bulma][], +[Hugo][], and [Webhook][]. + +### Apache Configuration + +This section disusses the [Apache][] configuration for this site. I +have broken this section into three sub-sections to make them easier to +digest. + +The [Apache][] configuration relies on the following modules: + +- [mod\_deflate][mod-deflate] (see note below) +- [mod\_http2][mod-http2] +- [mod\_macro][mod-macro] +- [mod\_proxy][mod-proxy] +- [mod\_rewrite][mod-rewrite] + +Note: It is safe for this site to enable [mod\_deflate][mod-deflate] +because it does not use [cookies][] and is not vulnerable to [BREACH][]. +and does not use [cookies][]. + +#### Virtual Host Configuration + +The [Apache][] virtual host configuration is modified as follows: + +- Unconditionally redirect from [HTTP][] to [HTTPS][] +- Unconditionally redirect to strip the `www.` hostname prefix +- Enable [HTTP/2][] +- Set security headers (discussed in [Security Headers](#security-headers)) +- Enable aggressive caching of image, script, and style assets + +Below is the [Apache][] virtual host configuration for this site with +extraneous comments and configuration for logging, [TLS][], and legacy +redirects removed: + +```apache +# unconditionally redirect to https://pablotron.org + + RewriteEngine On + RewriteRule ^/(.*)$ https://pablotron.org/$1 [R,L] + + + + # strip "www." prefix and enable mod_deflate + Use STRIP_WWW https://pablotron.org + Use MOD_DEFLATE + + # enable http2 + Protocols h2 http/1.1 + + # set restrictive content security policy + Header append "Content-Security-Policy" "default-src 'self'; img-src 'self' https://pmdn.org" + + # set remaining security headers + Header append "Strict-Transport-Security" "max-age=31536000" + Header append "X-Frame-Options" "SAMEORIGIN" + Header append "X-Content-Type-Options" "nosniff" + Header append "Cross-Origin-Opener-Policy" "same-origin" + Header append "Cross-Origin-Resource-Policy" "same-origin" + Header append "Access-Control-Allow-Origin" "https://pablotron.org" + Header append "Referrer-Policy" "strict-origin-when-cross-origin" + + # set permissions policy + Header append "Permissions-Policy" "camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), midi=(), payment=(), usb=()" + + # POST needed for /hooks + Header append "Access-Control-Allow-Methods" "POST, GET, HEAD, OPTIONS" + + # cache images, stylesheets, and javascript for 1 year + + Header set Cache-Control "max-age=31536000, public" + + + # expose webhook + + ProxyPass "http://localhost:9000/" + ProxyPassReverse "http://localhost:9000/" + + +``` + +[Download][apache-vhost.conf] + +#### Security Headers + +This site uses a strict [Content-Security-Policy][] header; it rejects +links to all external assets with one exception: references to images +hosted on are allowed. + +The trickiest part of restricting [Content-Security-Policy][] was +`style-src`; many content generation tools (including the [Markdown][] +table generator in [Hugo][]) break without `style-src 'unsafe-inline'` +(e.g., the ability to emit arbitrary `style` attributes). + +In order to work around the `style-src` issues I ended up [reconfiguring +the Hugo syntax highlighter](#hugo-configuration) and writing [a custom +Hugo table shortcode][hugo-shortcode-table] which only emits `class` +attributes for inline styling. + +The journey to a strict [Content-Security-Policy][] is documented in +this series of blog posts from October 2021: + +- [Hugo/Content-Security-Policy Impedance Mismatch (October 19, 2021)][post-headers-1] +- [TLS and Header Fixes (October 21, 2021)][post-headers-2] +- [The Nuclear Option (No More unsafe-inline) (October 25, 2021)][post-headers-3] + +The remaining security headers are explained in the following articles: + +- [Security headers quick reference][security-headers-quick-ref] +- [Goodby Feature Policy and hello Permissions Policy!][permissions-policy] +- [Permissions Policy Explainer][] +- [Referrer-Policy][] + +The security headers on this site earn an A+ rating from +[securityheaders.com][]: + +[{{< pe-figure "securityheaders-report" >}}][securityheaders-report] + +#### TLS Configuration + +The certificate for this site is issued by [Let's Encrypt][] and managed +automatically by [certbot][] with the [certbot-dns-linode][] plugin. + +The [Apache][] [TLS][] configuration is based on the intermediate +settings from the [Mozilla SSL Configuration Generator][ssl-config]. In +particular, only [TLS 1.2][] and [TLS 1.3][] are enabled, and the +insecure ciphers from [TLS 1.2][] have been disabled. + +```apache +# explicit list of cipher suites (from ssl-config.mozilla.org) +SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 + +# use server priorities for cipher algorithm choice +SSLHonorCipherOrder on + +# protocols to enable (only TLS 1.2 and TLS 1.3) +SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 +``` + +[Download][apache-tls.conf] + +This [TLS][] configuration earns an A+ result from the [SSL Labs SSL +Test][ssl-labs-ssl-test]: + +[{{< pe-figure "ssl-labs-report" >}}][ssl-labs-report] + +### Bulma Configuration + +The site [CSS][] based on the [Bulma][] with the following +modifications: + +1. All unused components removed +2. monokai style for [Chroma][] added +3. Styles for navbar icon highlighting and table captions added +4. dark mode styles added + +Here is the [SASS][]: + +```sass +// style.sass: based on bulma-0.9.3/sass/bulma.sass with the following +// changes: +// +// 1. all unused components removed +// 2. monokai style for chroma added +// 3. styles for navbar icon highlighting and table captions added +// 4. dark mode styles added +@charset "utf-8" + +// import chroma style +// +// generated with the following command: +// +// cd themes/hugo-pt2021/assets +// hugo gen chromaclasses --style=monokai > chroma.css +// +@import "chroma" + +@import "bulma-0.9.3/sass/utilities/_all" +@import "bulma-0.9.3/sass/base/_all" + +// elements +@import "bulma-0.9.3/sass/elements/button" +@import "bulma-0.9.3/sass/elements/container" +@import "bulma-0.9.3/sass/elements/content" +@import "bulma-0.9.3/sass/elements/image" +@import "bulma-0.9.3/sass/elements/table" +@import "bulma-0.9.3/sass/elements/title" +@import "bulma-0.9.3/sass/elements/other" + +// components +@import "bulma-0.9.3/sass/components/media" +@import "bulma-0.9.3/sass/components/navbar" + +// grid (reenabled, used for images) +@import "bulma-0.9.3/sass/grid/_all" + +// helpers +@import "bulma-0.9.3/sass/helpers/_all" + +// layout +@import "bulma-0.9.3/sass/layout/section" +@import "bulma-0.9.3/sass/layout/footer" + +// dim navbar icons by default +.navbar-item .menu-icon + opacity: 60% + +// highlight icons on hover +.navbar-item:hover .menu-icon + opacity: 100% + +// table captions below tables +table.table + caption-side: bottom + +// dark mode (2024-05-27) +@import "dark" +``` +[Download][style.sass.txt] + +With these changes the generated [CSS][] is 137 kB minified and 16 kB +minified and compressed. ### Hugo Configuration @@ -120,37 +442,56 @@ enhancement][]. The generated [HTML][] has been modified to: -- add support `go-import` +**TODO:** + +- add support `go-import` - add a [Mastodon][] `` tag. -- remove all unnecessary tags +- remove all unnecessary tags - to combine and [minify][] and [JavaScript][] and [CSS][] assets. - to add `integrity` attributes to `` and `