Martin Hähnel

WhileDo: More Cleanup

Published:
Tags:

Continuing yesterday's cleanup session in the blog repo:

The problem with cleaning up documentation is that in order to have a clean README, we need other things to be cleaned up as well. But I think we can start by removing things from the README we don't need. We can also structure the README in a way we'd like it to be.

I think a good README is one that a new user can read top to bottom when installing the project fresh. With that in mind I create the following outline at the top.

# blog-monorepo

This repo represents the personal blog infrastructure used to power blog.martin-haehnel.de.

## Overview

## Installation

## Setup

### Dev

### Prod

## HowTo

## Current Status

See ./docs/CHANGELOG.md.

It was hard to write about my writing, while writing so I didn't actually write a commentary text here documenting my though process while doing the thing.[1] But what came to mind just now is that the idea of this cleanup is to turn the blog repo public at some point in the future.

Anyway, to end this blog post, here's the new handwritten Overview section as it stands right now:

# blog-monorepo

This repo represents the personal blog infrastructure used to power blog.martin-haehnel.de.

## Overview

### JavaScript

This repo is made up of several "apps" that are all used in concert to power this blog:

- apps/blog - the [Eleventy](https://www.11ty.dev/)-powered Blog
- apps/blog-api - the dynamic parts of the blog (like favs and the guestbook) are implemented here, but also the plumbing to get (and resize) images (on the fly) from object storage

These apps are using the JavaScript echosystem and are powered by [pnpm](https://pnpm.io/), a nice npm replacement with [built-in monorepo support](https://pnpm.io/workspaces).

You'll find the following files on the root of the repo pertaining to pnpm:

- `package.json` - mostly for repo-level scripts, linting and formatting
- `pnpm-lock.yaml` - the pnpm-version of a lockfile
- `pnpm-workspace.yaml` - monorepo specific file, to tell pnpm where our "packages" (the apps making up the repo) live. It also includes the "catalog" for shared dependencies (this helps keep them on the same version, [pnpm docs](https://pnpm.io/catalogs))

There are package.json files in the `blog-api` and `blog` app folders, too.

To keep the code readable we use [eslint](https://eslint.org) (`eslint.config.js`) and [prettier](https://prettier.io) (`.prettierignore`, `.prettierrc`). For testing we use [Vitest](https://vitest.dev). To enforce these tools we use [Husky](https://typicode.github.io/husky/) so that commits need to pass our coding standards (that's what the `.husky` dir is about).

### Docker

We use [Docker](https://www.docker.com) to containerize the blog. In the local dev env we use a docker-compose file (`docker-compose.yml`) to run things. On prod, we use [Coolify](https://coolify.io). To simulate prod (i.e. to test the build process locally), we have another docker-compose file called `docker-compose.single.yml`.

There is a single Dockerfile (called `Dockerfile.single` for historical reasons). This is a multistep Dockerfile, which first builds the blog and then copies the results into the image. The container built from that image runs the migration tool [node-pg-migrate](https://salsita.github.io/node-pg-migrate/) (to make sure the DB is up to date) and then starts [Caddy](https://caddyserver.com) to serve the static files built by Eleventy and the blog-api (f.x. favs/guestbook/media routes).

The `.dockerignore` file limits the "Build context" by excluding files and folders ([docker's docs](https://docs.docker.com/offload/optimize/#dockerignore-files)).

Apart from that there is a `docker` directory which holds docker-specific files (like the `entrypoint.single.sh`) and configuration files relevant in a docker context (like for Caddy).

### Misc.

#### Files

- `AGENTS.md` this is a file meant to inform a Coding Agent (like Microsoft's Copilot or Open AI's Codex or whatever) about the repo ([more info](https://agents.md)).
- `CHANGELOG.md` a file keeping track what was done when, following the [keepachangelog.com](https://keepachangelog.com/en/1.0.0/) format
- `.env.1password` this holds plaintext env vars (like the MEDIA_BASE_URL should I ever want to run this blog on a different domain) and secrets using (1Password references) which work by using the 1Password cli ([1Password's docs](https://developer.1password.com/docs/cli/secrets-scripts)).

#### Folders

- `scripts` a place for various small scripts (i.e. to test or debug something)
- `docs` a mixed bag of files documenting ongoing projects, todos and similar

  1. Something I commented on in Writing About Coding, Writing About Writing ↩︎