Void-Homelab/docs/superpowers/specs/2026-06-08-kutt-url-shortener-design.md

# Design: Kutt URL shortener as a Void app

**Date:** 2026-06-08
**Status:** Approved (brainstorm), pending implementation plan
**Repos:** new **`Hynes/URLShortener-void-kutt`** (theme + deploy) + **`Hynes/Void-Homelab`** (void-v2 integration)

## Summary

Self-host **Kutt** (a modern Node URL shortener) **unmodified** in its own bare-metal
LXC behind `link.hynesy.com`, blackflame-themed via Kutt's **custom-CSS** support (no
fork → stays 100% upstream-clean). Surface it in the Void as a **Hybrid Apps item**:
an embedded themed Kutt UI for management, plus a small **Void-native card** for an
**update-tracker** and a **quick-add** box. Start **fully private** (CF Access over the
whole host) with a clean, no-rebuild path to **public-later** (and per-link
public/private via Kutt's multi-domain support).

## Background / constraints

- **Why Kutt** (vs Shlink): liked the UI, MIT, actively released (v3.2.5, 2026-05),
  Node/Postgres bare-metal install, and **themeable via custom CSS without forking** —
  so we ride upstream `npm` updates with zero merge conflicts.
- **User preferences honoured:** bare-metal-in-LXC (no Docker for long-term personal
  apps); blackflame styling; static IP + router MAC reservation per guest; HA-tag +
  Z→Z3 replication; backup before changes; document everything to the wiki + git.
- **The redirect-vs-auth split:** a shortener's redirect endpoint normally must be
  public, but the admin must be protected. We resolve this with a **CF Access toggle**
  (private now) rather than baking a split in.

## Decisions

| Decision | Choice | Rationale |
|---|---|---|
| App | **Kutt, stock** (pinned release) | Liked UI; themeable via CSS so no fork; upstream-clean. |
| Deploy form | **Bare-metal LXC** (Node + systemd) | No-Docker-for-keepers preference. |
| Database | **Shared `void-db`** (CT 310, PG 16) — dedicated `kutt` DB + least-priv role | One Postgres to back up / HA; no new DB service. |
| Redis | **Skipped** | Optional cache; unnecessary single-user. |
| Domain | `link.hynesy.com` → Traefik → Kutt | Clear, readable. |
| Access (now) | **Private** — CF Access over the whole host | Locked down first. |
| Access (later) | Relax CF Access on redirects; add a public 2nd domain for per-link public/private | No rebuild — policy flip + Kutt multi-domain. |
| UI | **Hybrid** — embed themed Kutt + a Void-native card | Keep the UI you liked + Void extras. |
| Feature parity w/ Shlink | Stock + QR Void-side; richer gaps via **upstream MRs** (separate effort) | Never fork Kutt. |

## Architecture

```
Browser ──(CF Access, Phase 1)── link.hynesy.com ── Traefik(mediastack) ── CT 113 kutt (Node)
                                                                                │ DATABASE_URL
                                                                          void-db CT 310 (PG 16, db=kutt)
Void (#/links) ── iframe ── themed Kutt UI
            └── Void-native card ── /api/links proxy (void-app, holds Kutt API key) ── CT 113 Kutt REST API
                                  └── update-tracker ── GitHub releases API + running version
```

## Components

### 1. Kutt LXC (CT 113 `kutt`)
- New unprivileged LXC on **Z**, static IP + router MAC reservation, **HA-tagged**,
  replicated Z→Z3, AppArmor `unconfined` (host requirement). 2 GB / 2 cores / small disk.
- **Node 20+**; Kutt checked out at a **pinned release tag** (e.g. `v3.2.5`) under
  `/opt/kutt`, user `kutt`. Install: `npm ci` → (build step if the release needs one)
  → `npm run migrate` → `npm start`, managed by **`kutt.service`** (systemd).
- Config via `/opt/kutt/.env` (mode 600): `DEFAULT_DOMAIN=link.hynesy.com`,
  `DB_*`/`DATABASE_URL` → void-db, `DISABLE_REGISTRATION=true`, trust-proxy / forwarded
  settings so Kutt knows its public origin, **no SMTP** (registration off, admin
  pre-seeded), one admin account + an API key.

### 2. Database (shared void-db)
- On CT 310 (`192.168.1.215:5432`, PG 16): create database **`kutt`** owned by a new
  **`kutt`** role (NOSUPERUSER, owns its DB + `public` schema so Kutt migrations run).
  Kutt manages its own schema via `npm run migrate`. Rides void-db's existing HA +
  backups; no impact on the `void` database.

### 3. Domain + CF Access (private → public)
- Traefik (mediastack `/docker/proxy/dynamic.yml`): router `link.hynesy.com` → CT 113
  Kutt port. Wildcard `*.hynesy.com` DNS already targets the tunnel.
- **Phase 1 (private):** CF Access app over **all of** `link.hynesy.com` (Google IdP,
  email allowlist) — admin *and* redirects private. (Embed then works via
  `void.hynesy.com`, not the raw LAN IP — same CF-cookie rule as Timelapse/AI-Usage.)
- **Phase 2 (public, later, separate effort):** remove CF Access from redirects; for
  per-link public/private add a public 2nd domain (e.g. `go.hynesy.com`, no CF Access)
  and use Kutt's multi-domain to choose a link's domain.

### 4. Theming (blackflame, no fork)
- Kutt's **custom CSS** hook: a blackflame stylesheet (palette `--accent #ff4f2e` etc.,
  Cinzel/Cormorant/JetBrains fonts, surfaces) applied to stock Kutt. Lives in
  `Hynes/URLShortener-void-kutt` and is dropped into Kutt's custom/override dir at deploy. **No Kutt
  source changes** → `npm`/release updates never conflict.

### 5. Void integration (the Hybrid)
- **Apps rail "Links"** (`#/links`, `public/views/links.js`): a Void header bar + a
  Void-native card (below) + an `<iframe src="https://link.hynesy.com">` (themed Kutt).
  Mirrors the Timelapse/AI-Usage embed views; added to the **Apps** sidebar section.
- **Void server proxy** (`lib/api/routes/links.js`, mount `/api/links`, owner-gated):
  forwards to Kutt's REST API over the LAN (CT 113 IP:port) with the **Kutt API key**
  held in void-app's `.env` (key never reaches the browser; LAN call works regardless
  of CF Access). Endpoints needed: create link (quick-add) + recent links + version.
- **Void-native card:**
  - **Update-tracker** — the proxy fetches `api.github.com/repos/thedevs-network/kutt/
    releases/latest` (cached ~6 h) and the running Kutt version; the card shows the
    version, an **"update available"** badge when they differ, and a changelog link.
    (Bare-metal = manual updates, so this is the "what's new / time to update" signal.)
  - **Quick-add** — paste a URL → `POST /api/links` → Kutt creates the short link → show
    + copy. Optional **QR** rendered Void-side (client lib) for any link.

### 6. Feature parity with Shlink
Kutt stays **stock**. Two non-forking lanes: (a) **now**, presentation-only wins like
**QR** in the Void card; (b) **later**, richer gaps (geo analytics, tags) as **merge
requests to Kutt upstream** — tracked as a *separate* project, **out of scope here**.

## Data flow
Create: Void quick-add → `/api/links` proxy (+API key) → Kutt → row in `kutt` DB → short
URL returned. Resolve: `link.hynesy.com/<slug>` → Kutt → 302 (CF-gated in Phase 1).
Update check: card → proxy → GitHub releases + running version → badge.

## Error handling
- Kutt down / proxy error → the card shows "Kutt unreachable" + the `↗ Open` fallback;
  the embed shows Kutt's own error. Void itself unaffected.
- GitHub API rate-limited/unreachable → update-tracker shows "version check unavailable"
  (cached last-known if any); never blocks the card.
- Missing/invalid Kutt API key → proxy returns a clear 502; quick-add disabled with a hint.

## Testing
- **vitest:** the `/api/links` proxy (mock Kutt API — create/list) and the update-tracker
  comparison logic (mock GitHub `releases/latest` + running version → badge true/false);
  the `links.js` view renders the card + iframe (jsdom).
- **Deploy smoke:** create a link via Kutt's API → `curl` the slug → 302 to target;
  confirm `link.hynesy.com` is CF-gated (302 to cloudflareaccess) in Phase 1.

## Out of scope (separate efforts)
- Phase-2 public access + per-link public/private second domain.
- Upstream MRs for geo/tags parity.
- Redis cache; SMTP/registration; multi-user.

## Repos & docs (standing rule)
- **`Hynes/URLShortener-void-kutt`** (created, `gitea@192.168.1.223:Hynes/URLShortener-void-kutt.git`): blackflame theme CSS, the
  LXC create/bootstrap + `kutt.service`, `.env.example`, deploy notes.
- **`Hynes/Void-Homelab`** (void-v2): the `links.js` view + `/api/links` proxy + Apps
  rail entry + CHANGELOG.
- **Wiki:** new "Kutt / Link Shortener LXC (113)" page under Hosts & Services.