update dabian base image version

Add decision document for node version

Author: kentcdodds

docs/decisions/021-node-version.md

@@ -0,0 +1,57 @@
+# Node.js LTS
+
+Date: 2023-07-03
+
+Status: accepted
+
+## Context
+
+Node.js has a regular release cycle which is documented in the
+[release schedule](https://nodejs.org/en/about/releases/). At the time of this
+writing, there are 5 stable maintained releases: 14, 16, 18, 19, 20. I'll refer
+you to that documentation to understand how the release cycle works.
+
+Deciding which version of Node.js to use for a project is a trade-off between
+using the latest features and stability.
+
+The Epic Stack is more focused on stabling shipping web apps than experimenting
+with the latest features which is where the Active Long-Term Support (LTS)
+version really shines.
+
+We deploy our apps in Docker containers, and there are various base images we
+can use as options which you can find on
+[the Node.js Docker Hub](https://hub.docker.com/_/node). Aside from the version,
+there flavors of the base image which are based on the Linux distribution used.
+Feel free to read more about the different flavors on Docker Hub. One of the
+goals for us here is to not ship more than we need in production.
+
+An additional consideration we'll add as context here is what version of Linux
+to have our base image built on. With the same pragmatic approach as the Node.js
+version we want to balance latest features with stability. We'll use the
+[Debian release cycle](https://wiki.debian.org/DebianReleases) as a guide for
+this.
+
+## Decision
+
+Use and current LTS version of Node.js as the default in the starter.
+
+We'll use the `slim` flavor of the node.js images.
+
+We'll use the `bookworm` flavor of the node.js images (which is the current
+stable version of Dabian: v12).
+
+## Consequences
+
+Folks should hopefully run into few compatibility issues. It's possible they
+will need features that are not back-ported to the current active LTS version,
+however it's trivial to update the Node.js version. Added documentation to the
+[managing updates](../managing-updates.md) docs should help people manage this.
+
+We'll need to update the Node.js version in the starter whenever the active LTS
+version changes.
+
+Folks who need a bunch more out of their operating system packages will need to
+switch from the `slim` flavor which only involves updating the `Dockerfile`. It
+is possible some will not realize they need more than `slim` until they run the
+Docker image (which many people will only do in production). However the
+likelihood of this impacting anyone is pretty low.

docs/managing-updates.md

@@ -1,5 +1,36 @@
 # Managing updates
 
+## Updating Node.js
+
+The Epic Stack runs a long-running Node.js server. It defaults to the current
+active LTS version of node
+([read the Node.js version decision document](./decisions/021-node-version.md)).
+
+If you wish to change the Node.js version, you can do so by updating the
+`engines.node` property in the `package.json` file.
+
+```json
+{
+	"engines": {
+		"node": "20.3.1"
+	}
+}
+```
+
+Make certain you do not use a version range here because this is used in the
+`./other/build-server.ts` to compile the express server code.
+
+You will also want to update the `Dockerfile` to use the same version of Node.js
+as the `package.json` file.
+
+```diff
+- FROM node:18-bookworm-slim as base
++ FROM node:20.3.1-bookworm-slim as base
+```
+
+You'll find the
+[Node.js versions available on Docker Hub](https://hub.docker.com/_/node).
+
 ## Within the Epic Stack
 
 When you create a new project with the Epic Stack, a bunch of code is generated

other/Dockerfile

@@ -1,7 +1,7 @@
 # This file is moved to the root directory before building the image
 
 # base node image
-FROM node:18-bullseye-slim as base
+FROM node:18-bookworm-slim as base
 
 # set for base and all layer that inherit from it
 ENV NODE_ENV production