Restructuring changkun.dechangkun.de 的架构重构

Since the “architecture upgrade” at the end of 2020, I have rarely touched the overall structure of changkun.de. At the end of The All in Go Stack, I expressed the hope that the new “organisational architecture”, backed by Go’s compatibility, would serve reliably for more than three years. Looking back now, it served for almost six years, and for most of that time it indeed had no major problems. But over those six years, more and more things accumulated on the server: whenever I needed a new feature, I would add a service, a route or a GitHub Action, and never come back to tidy up afterwards. Little by little, the website drifted back into an “organisationally chaotic” state.

This weekend (7 to 9 November 2026), I went through the whole thing again and carried out a complete restructuring. After the restructuring, every page on changkun.de is served by a single Go program; the blog no longer depends on any static site generator, and its repository contains only Markdown files; changkun.de, like golang.design, is now behind Cloudflare, with pages cached at edge nodes closer to readers; and upbot, the monitoring service I wrote in 2020, has been replaced by a status page running on GitHub Actions.

This post describes what accumulated on changkun.de over these years, the motivation for this restructuring, the architecture after it, and some of my experience of carrying it out with Claude Code.

Six Years of the New Age (2021–2026)

After the 2020 migration, the structure of changkun.de was roughly as follows: Traefik as the reverse proxy, in front of several Go services managed with Docker Compose, including the home page main, the blog, redir, midgard, upbot and so on. The blog itself was also a Go program, using Go 1.16’s embed feature to bundle the static files generated by Hugo into the binary. The one exception was modern-cpp-tutorial: as mentioned in Migration with Zero Downtime, Traefik cannot serve static files by itself, so an Nginx serving only static files was kept specifically for it.

This structure remained largely unchanged over the following years, but quite a lot was layered on top of it:

1. In November 2021, I wrote a simple static service in Go to replace Nginx for serving the static files under /www. The Nginx configuration, however, was never deleted; it stayed in the repository, and only the local development setup still used it. By the time of this restructuring, the static service ran three containers: one serving changkun.de, one serving golang.design, and one whose only job was to answer go get poly.red.
2. The blog was later changed to be built with Hugo in GitHub Actions and uploaded with rsync to the /www folder on the server, where the static service served it. Hugo itself stayed at version 0.91.2, from 2021.
3. Books, tutorials, the research page and so on were all published as folders under /www, and every folder needed its own route in Traefik.
4. The research page had a renderer of its own, and to render one README into one web page it vendored a copy of a Markdown library, adding up to almost sixteen thousand lines of code.
5. The home page main also carried an HTTP API for publishing “ideas”, deployed at api.changkun.de.
6. upbot probed each service at a fixed interval and emailed me through Mailgun when one was unavailable.
7. The DNS records of each domain were edited by hand in dashboards, and golang.design even still carried the mail records from its GoDaddy days.
8. The pages of each site had their own styles, essentially frozen in the year the site was born.

Of course, some of the tidying up had started before this. In 2021, redir’s storage moved from Redis to MongoDB; in February this year, urlstat moved from MongoDB to PostgreSQL; in August, redir moved onto the same PostgreSQL instance, and golang.design’s short link service was merged into the same redir along the way. This saved a good deal of data migration work for the restructuring.

Motivation for Restructuring

The first reason for this restructuring is that publishing something new had become more and more troublesome. Take the books and tutorials published this year as an example: each new site required:

1. Setting up the build in the repository’s GitHub Actions, and rsyncing the result to /www on the server
2. Adding a Traefik route for the folder in the infra repository
3. Logging into the server, pulling the infra repository and updating Traefik’s configuration

None of these steps is complicated in itself, but every new site added another section to the Traefik configuration, and it was easy to forget one of the steps.

The second reason is that the blog’s build had become unreliable once again. One of the main reasons for leaving Hexo in 2020 was that it had become hard to compile the whole blog smoothly on a new machine. Over these years Hugo stayed at 0.91.2, and the theme was my own fork with my own customisations, so upgrading Hugo would have meant adapting the theme all over again. In other words, the same problem had simply moved from the Node.js ecosystem to Hugo. Besides the posts, the blog repository also held Hugo’s configuration, the theme and the build scripts, more than three thousand lines in all.

The third reason is consistency. Each site had its own look, so a reader going from the blog to one of the books would see an entirely different page, with a different font, a different header and a different dark mode.

The fourth reason was only discovered during the restructuring: speed. Along the way I set up a new status page, and found that the median response time it measured for changkun.de was above 400 milliseconds. The cause is simple: the server is in Europe, while the status checks run on GitHub’s machines in the United States, so every request has to cross the Atlantic and come back. No amount of optimisation of the Go program itself can solve that.

Putting these reasons together, the goal of the restructuring became fairly clear:

Could all the pages of changkun.de be gathered into a single Go program, so that publishing anything takes only a git pull or copying files into a folder, without changing any configuration?

The post you are reading was rendered directly from Markdown by the restructured website, so the answer is yes.

Of course, it was only with coding agents like Claude Code that a restructuring of this scale became something that could be done in one weekend. We will come back to this later.

After the Restructuring (2026–)

Gathering All Pages into changkun/website

The home page repository changkun/main has been renamed to changkun/website. The pages of changkun.de are now all served by it:

• the home page, bundled into the binary with embed, as in 2020;
• every folder under /www/changkun.de, served at the path of the same name: once the folder exists it can be visited, without adding a route or restarting anything;
• golang.design, served from its own folder;
• the blog and the research page, rendered directly from checkouts of their repositories on the server;
• my Zotero library, under /library/, which can be shared with others by topic.

The corresponding Docker Compose configuration is very simple. The two folders are mounted read-only into the container, and environment variables tell the website where to read from:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

services:
  website:
    image: website:latest
    volumes:
      - /www/changkun.de:/www/changkun.de:ro
      - /www/golang.design:/www/golang.design:ro
    environment:
      WWW_DIR: /www/changkun.de
      WWW_CORS: /demos/
      WWW_SITES: golang.design=/www/golang.design

Here WWW_CORS names the paths that allow cross-origin access, and WWW_SITES lets the same program serve another site depending on the requested host.

Accordingly, changkun.de needs only one route in Traefik:

1
2
3
4

to-website:
  rule: Host(`changkun.de`) || Host(`ou.changkun.de`) || Host(`www.changkun.de`)
  priority: 1
  service: website

Traefik’s routes went down from 18 to 14, and most of what remains are redirects of old addresses and other services such as redir, urlstat and midgard. The static service, Nginx, the research page’s renderer and api.changkun.de have all been deleted; go get poly.red is now answered by redir, which was already doing the same for changkun.de/x and golang.design/x anyway. The website now has about 8,800 lines of Go, plus about 4,600 lines of tests.

Worth noting: the website’s Makefile and Dockerfile are almost the same as the ones in the 2020 post. It is still a cross-compile, followed by dropping the binary into an alpine image. Compared with back then, build now runs the tests first, and up removes old images afterwards, keeping only the two most recent versions so that a deploy can still be rolled back when needed:

1
2
3
4
5
6
7
8
9

NAME=website
VERSION = $(shell git describe --always --tags)
build: test
	CGO_ENABLED=0 GOOS=linux go build -o $(NAME)
	docker buildx build -t $(NAME):$(VERSION) -t $(NAME):latest --load .
up:
	docker compose up -d
	-docker images $(NAME) --format '{{.Tag}}' | grep -vx latest | tail -n +3 | sed 's/^/$(NAME):/' | xargs -r docker rmi
	-docker image prune -f

The Blog: Dropping Hugo and Rendering Markdown Directly

The blog repository changkun/blog now contains only Markdown files and the images used in the posts. Hugo’s configuration, the theme and the build scripts have all been deleted: 41 files, more than 3,100 lines. On the server, the website reads the checkout of the blog repository directly and renders the pages in Go (with goldmark), rendering them again when it notices that the checkout has changed.

Deployment has become very simple as a result. In 2020, the blog’s GitHub Action had to log into the server, pull the repository, build it and update the container:

1

ssh $USER@$DOMAIN "cd changkun.de/blog && git fetch && git rebase && make build && make up"

Now it only pulls the repository, with nothing to build:

1

ssh -i ~/.ssh/idkey "$USER@$DOMAIN" "git -C '$TARGET' pull --ff-only -q"

The biggest risk in dropping Hugo was the addresses. The posts on this blog have been linked from many places, and over its history the blog has used more than one URL scheme (remember the user-hostile /archives/year/month/id of the Third Age?). So before deleting the old build, I first recorded every address in the folder Hugo had generated on the server, more than 2,100 of them, and wrote down what each address should answer now: 1,079 answer with the page directly, 1,014 redirect for good to their new address, and 91 are content that is deliberately no longer published (such as old drafts, images that no post used, and the scripts and styles left over from old builds), which answer 404. This list was added to the website’s tests, and after the switch it was checked once more, one by one, against the live site.

Writing the Blog in the Browser

The blog now has an online editor at /blog/new. I can write a post or an “idea” in Markdown directly in the browser, with a live preview beside it, and images and videos can simply be dragged in. On publishing, the editor creates a commit in the blog repository through the GitHub API, which then triggers the GitHub Action above; once the server has pulled the repository, the post is online. Posts that are already published can be edited the same way, and on saving the editor checks whether the file on GitHub has changed in the meantime, to avoid overwriting changes made elsewhere. Since the posts here all have an English and a Chinese version, the editor can also translate a post written in one language into the other before it is published.

The “ideas” that used to be published through api.changkun.de now go through this editor as well, so the API was deleted along with it.

One Login for the Whole Site

Both the library and the editor need to confirm that the visitor is me. There is now only one login page for the whole site, at /login: the browser signs in with my latere account (a PKCE flow), and after verifying the token the server issues a cookie of its own. Logging out also logs out of latere, and every page on changkun.de is logged out together.

Moving to Cloudflare: DNS and the Edge Cache

In 2020, in Migration with Zero Downtime, I wrote:

If you ask why I don’t use Cloudflare: laziness. On one hand, I don’t want a personal website to take on too many dependencies; on the other, golang.design has Cloudflare enabled, which makes it a kind of A/B comparison with changkun.de.

This A/B comparison ended up running for six years. This time, changkun.de has finally moved to Cloudflare too.

First, DNS. The records of these domains used to be edited by hand in their dashboards. Now the DNS records of all five domains, changkun.de, changkun.org, golang.design, poly.red and changkun.us, are written in one file in the infra repository and pushed to Cloudflare with DNSControl. For example, part of the records of changkun.de:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

D("changkun.de", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
  A("@", SERVER, CF_PROXY_ON),
  A("www", SERVER, CF_PROXY_ON),
  A("ou", SERVER, CF_PROXY_ON),
  A("blog", SERVER, CF_PROXY_ON),
  // ssh and the publishing workflows connect by this name, which is never
  // proxied: Cloudflare's proxy does not carry ssh.
  A("ssh", SERVER),
  // ...
);

Note that a DNSControl push deletes any record not written in the file, so every push should be preceded by a dnscontrol preview. Also, Cloudflare’s proxy does not carry SSH, so the record ssh.changkun.de must stay unproxied; the publishing workflows of the various repositories all connect to the server through it.

Next, caching. The website adds a Cloudflare-CDN-Cache-Control header to every public response:

1

const edgeControl = "max-age=60, stale-while-revalidate=604800, stale-if-error=604800"

What it means: a page is cached at Cloudflare’s edge nodes for one minute, and within that minute it is answered directly by the edge; after one minute, Cloudflare still answers with the cached page first, while requesting the new version from the server in the background; and if the server cannot be reached for a while, Cloudflare can keep answering with the cached page for up to a week. As a result, after a page is changed, the next visit after one minute makes Cloudflare fetch the new version, so the cache never needs to be purged by hand. The reason for using Cloudflare-CDN-Cache-Control rather than Cache-Control is that only Cloudflare reads the former, and it does not pass it on to the browser, so the browser’s caching behaviour stays the same. The Cache Rule configured on the zone caches only responses that carry this header, so pages that differ from person to person, such as the library, the editor and the login page, are never cached.

There was one more problem to deal with here: caching assumes that a page is the same for everyone. Before this, the “Edit” link on a post was added by the server only after it had confirmed that the visitor was me. So now every post carries this link, hidden by default, and a few lines of script show it when the browser has a cookie indicating that I am signed in. This cookie grants no permission by itself; the editor still checks the real session.

Judging from the results, the effect is quite noticeable: in the first few hours after it went live, the median response time measured by the status checks went from about 420 milliseconds to about 190 milliseconds for changkun.de, and from about 410 milliseconds to about 130 milliseconds for golang.design. It should be said that the status checks open a new connection every time; on a connection that is already open, a page takes only about 30 milliseconds for me in Europe. Of course, a page that nobody has visited for a long time still has to be fetched from the server once on its first visit.

A Status Page on GitHub Actions

upbot has been retired, and its place has been taken by a GitHub Actions workflow in the changkun/status repository, which checks every site and service every five minutes, publishes the results at changkun.github.io/status, and opens an issue and notifies me as soon as a service has a problem.

This may look contrary to the 2020 principle of “building in-house wherever possible”, but the reason is straightforward: upbot ran on the same machine as the services it monitored, so if the machine itself had a problem, upbot had the same problem, whereas GitHub Actions does not depend on this server. I had also planned to give the status page the domain status.changkun.de, but GitHub Pages never issued a certificate for it, even after removing the domain and adding it again, so for now it stays on github.io.

One Design for All Pages

All sites now share one design: the home page, the blog, the research page, the library, the books (Bayesian Optimization, AI Alignment, An Unverifiable World, Modern C++ Tutorial), the Swedish and German tutorials, the dashboards of redir and urlstat, and the status page. They all use the Inter font and a mostly black-and-white palette, share the blog’s header, and the choice of light or dark mode stays the same across the pages of changkun.de. In addition, every reading page now counts its readers with urlstat and shows the page views and visitors in its footer.

The Services Today

After the restructuring, the overall structure of changkun.de is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

                       readers
                          │
            Cloudflare (DNS, edge cache)
                          │
                DigitalOcean Droplet
                          │
                       traefik
     ┌──────────┬─────────┼─────────┬──────────┬──────────────┐
  website     redir    urlstat   midgard     gossa     rankui study
     │          └────┬────┘
   /www           postgres

• traefik: the reverse proxy
• website: all pages of changkun.de and golang.design
• redir: short links and Go import paths, for changkun.de, golang.design and poly.red
• urlstat: page view statistics
• postgres: the database shared by redir and urlstat
• midgard: my clipboard service
• gossa: golang.design’s SSA playground
• rankui study: a user study, at poly.red/study

How to rebuild the whole server, from a backup or from scratch, is written in the README of the infra repository.

Restructuring with Claude Code

The 2020 migration took the first three days of my Christmas holiday, and I wrote all of the code myself, line by line. This restructuring took one weekend, from Friday night to Monday morning, and touched 14 repositories with 174 commits in total, including 79 in website, 33 in infra, 15 in status, 11 in blog and 9 in redir. This time, however, most of the code was not typed by me, but written by Claude Code.

In practice, I ran several Claude Code sessions at the same time, each responsible for different repositories: one for the website, one for a book, one for the tutorials, and so on. My work was mainly to describe clearly what I wanted, read the changes it brought back, and then decide whether to accept them or ask for further changes. Compared with writing the code myself, more of the time went into reading and judging.

One rule held throughout: Claude Code could change code, commit and push, but every operation involving production, such as deploying, pushing DNS, changing Cloudflare settings, or deleting folders or containers on the server, had to be run by me. It wrote the command, and I read it before typing it myself. This is indeed somewhat slower, but it guarantees that no change reached production without my having seen it.

Of course, the process was not entirely smooth, and a few of the problems along the way are worth recording:

1. The git on the server was older than 2.28, while the website’s tests used git init -b. Since make build runs the tests first, one deploy on the server was stopped by the failing tests.
2. After caching was enabled, Cloudflare at one point served the Swedish tutorial with new HTML and an old stylesheet. The fix was to publish the styles and scripts into a folder named by a hash of their content, so that when the content changes, the address changes with it.
3. The status.changkun.de certificate problem mentioned above.
4. The “Edit” link mentioned above: to make the pages cacheable, I first had to find every place on them that differed from person to person.

Retrospective

This post first reviewed the services and problems that accumulated on changkun.de over the six years from 2021 to 2026, then described the motivation for this restructuring and the architecture after it: all pages are served by one Go program, changkun/website; the blog has dropped Hugo and is rendered directly from Markdown; DNS is managed in one place with DNSControl, and pages are cached at Cloudflare’s edge nodes; and monitoring has been handed to GitHub Actions. Finally, it briefly described the process of carrying out the restructuring with Claude Code.

Compared with 2020, this restructuring did not actually introduce any new technology: Go, Docker Compose and Traefik are all still there, and even the Makefile and Dockerfile have barely changed. The change was mainly to go through what had been layered on over these years again, merge the services that could be merged, and delete the parts that were no longer needed.

These services are all open source. Interested readers can find them at the following links:

• https://github.com/changkun/website
• https://github.com/changkun/blog
• https://github.com/changkun/infra
• https://github.com/changkun/redir
• https://github.com/changkun/urlstat
• https://github.com/changkun/midgard
• https://github.com/changkun/status

The design of the New Age lasted almost six years. I hope the structure after this restructuring will last even longer.

Changkun Ou

9 November 2026