Early Architecture Notes - Portfolio + Comments Stack

Portfolio + Comments Stack

Historical Architecture Document — Early Thinking on Site Structure

Static site (Astro) + federated comments (Cactus Comments, Matrix-backed) + reverse proxy (Caddy).

This fits comfortably on a 1–2GB VPS because only Caddy runs persistently on the box, serving static files. Astro only runs at build time, on your own machine — nothing Node-based stays running on the server.

Note

This document represents early architectural thinking from the project’s formative stages. The actual implementation evolved to use Hugo instead of Astro, and the comments system was reconsidered. It’s preserved here for historical context and to show the evolution of the lab’s technical decisions.

1. Scaffold the portfolio (on your machine, not the VPS)

npm create astro@latest my-portfolio -- --template minimal
cd my-portfolio
npm run dev   # preview at localhost:4321

Build content under src/pages/ — one .astro or .md file per project writeup (hardware, media synthesis, Linux, whatever). When ready to publish:

npm run build   # outputs static files to ./dist

2. Drop in Cactus Comments

In the layout template your writeups share (e.g. src/layouts/Post.astro), add before </body>:

<link rel="stylesheet" href="https://latest.cactus.chat/style.css" />
<script
  src="https://latest.cactus.chat/cactus.js"
  data-default-homeserver-url="https://matrix.cactus.chat:8448"
  data-server-name="cactus.chat"
  data-site-name="your-site-name"
  data-comment-section-id="{unique per post — the page slug works}"
></script>
<div id="comment-section"></div>

This points at the public Cactus appservice and the public matrix.cactus.chat homeserver — there is nothing to self-host yet. Visitors can comment via any Matrix account on any homeserver, and continue the thread in a full Matrix client if they want.

3. Caddy on the VPS

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

/etc/caddy/Caddyfile — this is the entire config:

yourdomain.com {
    root * /var/www/portfolio
    file_server
}

No certbot, no cron job. Caddy sees the domain name in the site block and provisions/renews the TLS cert itself.

sudo systemctl enable --now caddy
sudo systemctl reload caddy   # after any Caddyfile edit

4. Deploy loop

From your machine, after npm run build:

rsync -avz --delete dist/ user@yourvps:/var/www/portfolio/

New writeup → npm run build → rsync → live. No build step ever runs on the VPS itself, which is why the 1–2GB box is fine.

Later, optional

If you eventually want full ownership of comment data instead of relying on the public Cactus infrastructure, self-host just the appservice — a small Python/Flask service, the only piece here with any real infra weight, and not required to launch.