# Developer Homepage

A static portfolio site (vanilla HTML/CSS/JS + a fake terminal easter egg)
packaged as an nginx container and deployed with Podman Quadlet.

## Build & Run with Podman

### Build the image

```bash
podman build -t homepage:latest .
```

### Run the container

The image runs `build.sh` itself and copies the hashed `dist/` output into the
nginx html root, so the built site is already inside the image:

```bash
podman run --rm -p 0.0.0.0:8080:8080 homepage:latest
```

To iterate on `src/` without rebuilding the image, build locally and bind-mount
the **built** output over the html root — mount `dist/`, never `src/`, because
`index.html` requests content-hashed filenames:

```bash
./build.sh
podman run --rm -p 0.0.0.0:8080:8080 -v ./dist:/usr/share/nginx/html:z homepage:latest
```

Visit `http://localhost:8080` in your browser.

## Serving & configuration

`nginx.conf` is copied into the image as the site config. It listens on
**8080 over plain HTTP**, serves the hashed build, declares the hardening
headers (`X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`,
`Content-Security-Policy`), serves `index.html` with `no-cache`, and caches the
hashed assets as `immutable` for a year.

Known gap (audit finding M-4, Phase 03): nginx does not merge `add_header`
across configuration levels, so the `location` blocks that set their own headers
drop the server-level security headers — measured against the built image, `/`,
`/index.html` and a hashed asset currently get only the cache headers. Every
`add_header` block must repeat the hardening headers until that phase lands.

TLS and HSTS are the job of the reverse proxy in front of the container
(`reeseapps.com` terminates at the Caddy edge). Do **not** add
`Strict-Transport-Security` or a `listen 443` block to `nginx.conf`.

## Deploy with Quadlet

The `homepage.container` Quadlet unit is **not** tracked in this repository — it
lives with the deployment host's config. Install it under
`~/.config/containers/systemd/` (copy it from wherever the host's unit files are
kept):

```bash
mkdir -p ~/.config/containers/systemd
cp <deploy-config>/homepage.container ~/.config/containers/systemd/
```

It must publish host port 8080 and use the image CI publishes:
`gitea.reeseapps.com/services/homepage` (`main` on every push to `main`, plus
one tag per release).

Quadlet is a systemd generator: it turns `homepage.container` into a
`homepage.service` unit when systemd regenerates units, so manage it under the
`.service` name:

```bash
systemctl --user daemon-reload
systemctl --user start homepage.service
systemctl --user status homepage.service
```

Auto-start on boot comes from the unit's `[Install]` section (e.g.
`WantedBy=default.target`), which the generator applies while generating — the
Quadlet services are transient, so `systemctl enable` has no effect on them;
re-run `systemctl --user daemon-reload` after editing the unit. For a user-mode
unit that must come up without a login session, enable lingering once:
`loginctl enable-linger $USER`.

## Development

Source files live in `src/`: `index.html`, `style.css`, `script.js` and the
flat terminal modules (`terminal.js`, `terminal-commands.js`,
`terminal-vim.js`, `terminal-achievements.js`). Keep every `.js` file flat in
`src/` — `build.sh` only hashes root-level files.

```bash
npm install        # installs the pinned @playwright/test dev dependency
./build.sh         # src/ -> dist/ (content-hashed asset names)
npm test           # Playwright E2E suite against dist/ on 127.0.0.1:8123
```

Always build before testing: the suite exercises the built artifact in `dist/`,
never `src/`. `npm test` starts (or reuses) its own static server, so no manual
server is needed. Rebuild the image (`podman build`) after changing `src/`.

Requires Node.js 20+ (the `@playwright/test` engine floor) and the Chromium
revision cached for the pinned Playwright version — run
`npx playwright install chromium` if it is missing, and see `AGENTS.md` before
bumping the pin.

The validation gate the phased pipeline runs per task is `.agents/validate.sh`
(full E2E suite plus repo-hygiene checks): `bash .agents/validate.sh`.