← jeffpelton.com dev.jeffpelton.com

Hosting a site on dev.jeffpelton.com

How any project publishes a static site to dev.jeffpelton.com, at a path or its own subdomain, once or on every merge.

Any project that builds to a folder of static files (HTML, JS, CSS, images, WASM and so on) can live at https://dev.jeffpelton.com/<name>/, or at its own subdomain, https://<name>.dev.jeffpelton.com/. It works much like Vercel or Netlify for static sites: publish once with one command, and optionally let GitLab CI republish on every merge to the default branch. There's no server to run, and the site is listed on the index page unless it opts out.

Games go to wefav.com instead. Since 2026-10-08 every game is published there with its own tool (~/wefav.com/bin/wefav.cjs, guide in ~/wefav.com/PUBLISHING.md), and the games that used to be here redirect to the same path on wefav.com. This site is for everything else: experiments, simulations and small tools. A name that moved can't be published here again; devsite says so and points at wefav.com.

Under the hood it's an S3 bucket behind CloudFront (HTTPS, HTTP/2 and 3, gzip/brotli), with a small dependency-free CLI, devsite.cjs, and a GitLab CI component. This page is also served as raw markdown at /hosting.md.

Playbook: "publish this to dev.jeffpelton.com"

This is for an agent (or a person) working in some project who has been asked to publish, deploy or host it on dev.jeffpelton.com (or "to ~/dev.jeffpelton.com"). Run everything from the project's root. devsite below means:

  • on Jeff's machine: node ~/dev.jeffpelton.com/bin/devsite.cjs
  • anywhere else: curl -fsSL https://dev.jeffpelton.com/_site/devsite.cjs | node -

Steps:

  1. Configure. Run devsite init. This writes devsite.json (see below) with a name guessed from package.json or the folder name, the build folder, and a title. Adjust the name and description, and run devsite list to make sure the name isn't taken by another project.

  2. Pick how it's served (see Choosing a mode): the default path mode, or "subdomain": true, plus "spa": true if it uses client-side routing. Then set the build's base path to match: /<name>/ for path mode, / for a subdomain (see Build for a subpath).

  3. Publish once. Build, then run devsite publish. If it warns about root-relative URLs outside /<name>/, fix the base path and publish again.

  4. Verify. Open the URL that publish printed in a browser and check that the page loads with no failed requests. If no browser is available, curl the page and a couple of its assets.

  5. Add analytics. Every site here reports cookieless page views to Jeff's Umami at s.wefav.com. Put this tag in the <head> of every page the site ships:

    <script defer src="https://s.wefav.com/js/site.js" data-website-id="e93cef2d-3c5c-43f9-ad6e-df34fa4a5cbe" data-domains="dev.jeffpelton.com"></script>
    
    • Path mode: use it exactly as it is. All path-mode sites share one Umami website, and Umami tells them apart by path.
    • Subdomain mode: set data-domains to the site's own host, <name>.dev.jeffpelton.com.
    • Don't change the other attributes. data-domains stops local dev and preview hosts from being counted. The tag needs no key, so there is nothing secret to protect.
    • Custom events (optional): mark the moments that matter with window.umami?.track('name', { … }), for example a game's play, result and share. Guard with ?., because the script loads deferred.
    • Builds for other hosts: leave the tag out of builds for game portals such as Poki, which forbid outside requests.
    • Check: after publishing, the page should load https://s.wefav.com/js/site.js and POST to https://s.wefav.com/js/v1/e, getting a 200. Headless browsers are filtered as bots, so a Playwright visit won't show up in the stats.
  6. Fill in the index listing. Every published site is listed on the index page by default. That's how Jeff keeps track of everything published here, so treat the listing as part of the job. In devsite.json:

    • title: the project's real name, not the repo slug.

    • description: one sentence saying what it is and how to use or play it.

    • tags: 1–4 short lowercase tags (game, tool, three.js, ai, …).

    • links: optional extras (a source repo if it's public, a related site).

    • Keep unlisted false unless Jeff asked to hide the site (for example unfinished or private work). devsite list still shows unlisted sites to Jeff.

    • Preview: each index entry is a card showing the site's share card (its og:image) and a Demo button when there's a demo video. Jeff wants both whenever possible, so the experiment is captured as fully as it can be. See Previews:

      • Give the site a 1200×630 share card: og:image (absolute URL) in its index.html, plus a real <title>, description, og:title and og:description. publish picks the card up automatically.
      • Ask Jeff whether he has a demo video (a file, or a YouTube/Vimeo link). If not, offer to record one. Set it as "video" in devsite.json.
    • Link back. Put a visible link to dev.jeffpelton.com on the site, so a visitor who liked it finds everything else. For games, put it on the end or result screen, where a player decides what to do next, e.g. "More small games at dev.jeffpelton.com". Open it in a new tab. A studio name and branding may replace this wording later; the link is the part that matters.

    Publish again after editing; the listing updates immediately. publish prints which preview it found.

  7. Auto-publish on merge. Do this when the project's origin is on git.wefav.com (git remote -v). Run devsite ci-setup. It:

    • adds the publish component to .gitlab-ci.yml: it creates the file, or appends to one that has no include: list, or prints the entry to add to an existing include: list;
    • picks the build: command from the lockfile. Check it, and override with --build "<cmd>" if needed;
    • sets the publish key as masked, protected CI variables on the project.

    Commit devsite.json and .gitlab-ci.yml. From then on, every push or merge to the default branch republishes the site.

    • Not on GitLab yet? Skip this step and tell Jeff. Once the project is pushed, devsite ci-setup finishes it. Don't create GitLab projects unless asked.
    • The first push to the default branch deploys. Follow the project's normal branch/MR habits, and don't push to master just to try it out unless Jeff says so.
  8. Suggest a write-up (optional). Offer Jeff a short note about the project on the index site. If he wants one, add ~/dev.jeffpelton.com/content/notes/YYYY-MM-DD-<name>.md:

    ---
    title: Voxel Golf
    description: Mini golf on a voxel island, built in a weekend with three.js.
    site: voxel-golf
    ---
    
    One to three short paragraphs: what it is, how it was made, what's interesting or next.
    

    site: links the note and the site both ways (an "Open …" link on the note, a "write-up" link on the site's listing). Commit only that file in jeff/dev.jeffpelton.com and push to main; its CI redeploys the index site in about a minute. Don't change anything else in that repo.

  9. Report back: the URL, whether it's listed, whether analytics is on, whether it links back, which previews it has (share card, demo video), whether auto-publish is set up, whether there's a write-up, and anything left for Jeff to do.

Don't touch the bucket, the CloudFront distribution, the key-value store or the IAM user directly. Those are managed in ~/aws-jeffshouse.

Choosing a mode

Two flags in devsite.json decide how a site is served. Both default to false, and both can be changed later by editing devsite.json and publishing again.

Situation Settings URL Base path
Most sites: games, toys, multi-page static sites (defaults) dev.jeffpelton.com/<name>/ /<name>/
Client-side routing (React Router, Vue Router, …) "spa": true dev.jeffpelton.com/<name>/ /<name>/, and the router's basename /<name>
Needs to be served from /, or needs its own origin "subdomain": true <name>.dev.jeffpelton.com/ /
Both "subdomain": true, "spa": true <name>.dev.jeffpelton.com/ /

Choose subdomain when the project:

  • has a service worker or PWA manifest scoped to /,
  • hard-codes root-absolute paths it can't easily change,
  • registers OAuth or other redirect URLs,
  • needs storage and cookies that no other experiment can read or overwrite (anything with a login or data worth keeping),
  • or should simply have a short URL to share.

It costs nothing extra: no per-site DNS, certificate or setup.

Choose spa when the app routes in the browser with real paths (/level/2, not /#/level/2). Every URL whose last segment has no file extension then serves the site's index.html, and the router takes it from there. Real files (anything with an extension) are still served as usual. In spa mode, extensionless URLs never reach other HTML files, so link to extra pages by file name (docs/index.html) if you have any. Without spa, a URL like /level/2 redirects to /level/2/ and 404s unless that folder exists.

When a site switches to subdomain, its old dev.jeffpelton.com/<name>/… URLs permanently redirect to the subdomain. A subdomain for a site that isn't in subdomain mode redirects to the site's path URL. After changing either flag, give it about 30 seconds before testing, because CloudFront's edges pick up the new routing within that time.

devsite.json

This file sits in the project root and is committed with the project. It's the one source of truth for both local and CI publishes.

{
  "name": "voxel-golf",
  "dir": "dist",
  "title": "Voxel Golf",
  "description": "Mini golf on a voxel island. Drag to aim.",
  "tags": ["game", "three.js"],
  "unlisted": false,
  "video": "https://youtu.be/dQw4w9WgXcQ",
  "subdomain": false,
  "spa": false,
  "immutable": ["assets/"],
  "links": [{ "label": "source", "url": "https://git.wefav.com/jeff/voxel-golf" }]
}
Field Meaning
name Gives https://dev.jeffpelton.com/<name>/ (or https://<name>.dev.jeffpelton.com/). Lowercase letters, digits and dashes, 1–63 characters. Required.
dir Folder to upload. Default dist. For plain HTML with no build step, use the folder holding index.html, or . for the project root. .git, node_modules, .env*, .gitlab-ci.yml and devsite.json are never uploaded.
title, description, tags What the index page shows.
unlisted true keeps the site live at its URL but off the index page, the sitemap and sites.json.
image Index card image. Default: the og:image in the site's index.html, so usually leave it out. An absolute URL, or a path inside the site.
video Demo video: a YouTube or Vimeo URL, a video file in the site (demo.mp4), a file uploaded with devsite media (_media/demo.mp4), or any other URL (opened in a new tab).
subdomain true serves the site at https://<name>.dev.jeffpelton.com/ from its own root. See Choosing a mode.
spa true serves index.html for every extensionless path, for client-side routers.
immutable Folders whose files have content hashes in their names (Vite assets/, Astro _astro/). Browsers cache these for a year. Leave it out if unsure.
links Extra links shown on the index entry (label + absolute url).

Every field can be overridden on the command line: --name, --dir, --title, --description, --tags a,b, --unlisted / --listed, --subdomain / --no-subdomain, --spa / --no-spa, --image <url|path>, --video <url|path>.

The index lists sites newest first by the date each was first listed. Republishing (every CI deploy) doesn't move a site. To move one back to the top on purpose, say for a big update, publish it once with --bump.

Previews

The index shows every site as a card: its share card image on top, and a Demo button when it has a video. Video files also play silently when you hover over the card. The button opens the video in a lightbox; YouTube and Vimeo play embedded. A write-up note with site: <name> shows the video (or the card) at the top. Sites with neither get a generated placeholder, so it's worth adding both.

Share card

  • A 1200×630 PNG or JPG in the site's root, for example public/og.png in a Vite project, so it ships as og.png.

  • Referenced from index.html with an absolute URL, the one social sites need:

    <meta property="og:title" content="Voxel Golf">
    <meta property="og:description" content="Mini golf on a voxel island. Drag to aim.">
    <meta property="og:image" content="https://dev.jeffpelton.com/voxel-golf/og.png">
    <meta property="og:image:width" content="1200">
    <meta property="og:image:height" content="630">
    <meta name="twitter:card" content="summary_large_image">
    

    For a subdomain site the image URL is https://<name>.dev.jeffpelton.com/og.png.

  • Make it look good: the game's title in big type over a real screenshot or key art works well. One way is to build the card as an HTML page, then screenshot it at exact size: npx -y playwright@1 screenshot --viewport-size "1200, 630" --wait-for-timeout 1500 file://$PWD/og-card.html public/og.png (add --channel chrome to use an installed Chrome instead of downloading one).

  • publish warns when the card is missing, relative, or points at a file that isn't in the build.

Demo video

  • YouTube / Vimeo: "video": "https://youtu.be/<id>" (or a youtube.com/watch, shorts or vimeo.com URL). Nothing to upload. If there's no share card, the YouTube thumbnail is used instead.

  • A video file: MP4 (H.264) plays everywhere. Keep it short (15–90 s) and ideally under 30 MB, and it can be silent. Encode it with:

    ffmpeg -i input.mov -vf "scale='min(1920,iw)':-2" -c:v libx264 -crf 26 -preset slow -pix_fmt yuv420p \
      -movflags +faststart -an demo.mp4
    

    Then either:

    • put it in the build (public/demo.mp4) and set "video": "demo.mp4" (fine for small files), or
    • keep it out of git: devsite media demo.mp4 uploads it once to /<name>/_media/demo.mp4, then set "video": "_media/demo.mp4". Publishes (including CI) never delete _media/, so upload it again only when the video changes.
  • No video yet? Offer to record one. Playwright can drive the site and record the session:

    // record.mjs — npx -y playwright@1 install chromium, then: node record.mjs
    import { chromium } from 'playwright';
    const browser = await chromium.launch();
    const context = await browser.newContext({ viewport: { width: 1280, height: 720 },
      recordVideo: { dir: 'recordings', size: { width: 1280, height: 720 } } });
    const page = await context.newPage();
    await page.goto('https://dev.jeffpelton.com/<name>/');
    // ...play: clicks, key presses, waits that show the best 20-40 seconds...
    await context.close();   // writes recordings/<id>.webm
    await browser.close();
    

    Convert the .webm to demo.mp4 with the ffmpeg command above. WebGL/three.js sites may need chromium.launch({ args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader'] }) when there's no GPU. Show Jeff the result before using it.

Build for a subpath

(Path mode only. Subdomain sites use the default base /, and publish warns if their HTML still points into /<name>/.)

In path mode the site is served from /<name>/, not /, so its build has to know that. Otherwise /assets/app.js points at the site root and 404s. publish warns when it finds root-relative URLs outside /<name>/.

Tool Setting
Vite (React, Vue, Svelte, vanilla) base: '/<name>/' in vite.config
Astro base: '/<name>' in astro.config (and use import.meta.env.BASE_URL for links)
Next.js output: 'export', basePath: '/<name>', then dir: "out"
SvelteKit adapter-static, paths: { base: '/<name>' }
Plain HTML relative URLs (src="app.js", not src="/app.js")
React Router / Vue Router (with spa) basename /<name> (createBrowserRouter(routes, { basename: import.meta.env.BASE_URL }))

Auto-publish from GitLab CI

The whole CI setup for a project is this include. devsite ci-setup writes it for you:

include:
  - component: git.wefav.com/jeff/dev.jeffpelton.com/publish@main
    inputs:
      build: "npm ci && npm run build"

It adds one job, devsite-publish. The job runs only on the default branch, so a merge to master (or main) publishes. It installs the AWS CLI if the image lacks it, runs build, downloads the current devsite.cjs, and runs publish, which reads devsite.json as usual. Publishes run one at a time per project (resource_group).

Input Default
build npm ci && npm run build Any shell command. Use "true" for sites with no build step.
image node:22-alpine Needs Node 18+. Alpine and Debian-based images both work.
stage deploy Set it if the project's stages: list has no deploy.

Requirements:

  • The key: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY CI variables, set by devsite ci-setup (or devsite ci-setup --vars-only to only set them). This needs Jeff's machine: the key is copied from its local dev-jeffpelton AWS profile using glab.
  • A protected default branch: the variables are protected, so only protected branches see them. GitLab protects the default branch automatically, and MR branches never get the key.
  • git.wefav.com: the component lives in the jeff/dev.jeffpelton.com project there.

Routing rules

  • /<name>/ serves /<name>/index.html, and /<name>/about/ serves /<name>/about/index.html. On a subdomain it's the same without the /<name> prefix.
  • Without spa, /<name> (no trailing slash) permanently redirects to /<name>/, and so does any path whose last segment has no file extension. Every file needs an extension.
  • With spa, every extensionless path serves the site's index.html (see Choosing a mode).
  • A missing file returns the shared 404 page with a real 404 status.
  • There's no server-side code, redirects or custom headers. Anything dynamic has to happen in the browser or call an API somewhere else.

Caching

  • Every file is served with max-age=0, must-revalidate to browsers (so a reload always sees the latest publish) and cached at the CDN until the next publish invalidates /<name>/*.
  • devsite media invalidates a file only when it replaces one already there. A new file name has never been cached, so it's live as soon as the upload finishes. JSON files uploaded with devsite media (data, indexes) are cached at the CDN for 10 seconds instead and never invalidated: after a re-upload, readers see the new copy within ~10 s. Need a non-JSON file to change right away? Upload it under a new name and point at that.
  • Folders listed in immutable get max-age=31536000, immutable. Only list folders whose file names change when their content changes.
  • publish waits for the CDN to clear its cached copies, which usually takes under a minute. When it prints live: the new version is being served. --no-wait skips the wait.

All commands

devsite init                        # write devsite.json
devsite publish [--dry-run]         # upload dir -> /<name>/ (--dry-run: list changes, touch nothing)
devsite ci-setup [group/project]    # auto-publish on merge: CI include + key (--build, --vars-only, --ci-only)
devsite media <file>                # upload a demo video to /<name>/_media/ (kept across publishes; see Caching)
devsite list                        # every site, including unlisted, with its source repo
devsite unpublish <name> --yes      # delete a site and drop it from the index
devsite doctor                      # check the AWS CLI + credentials + bucket access
devsite reindex [--previews]        # rebuild the index listing (--previews: re-read every site's og:image)

To vendor the CLI instead of piping it from curl: curl -fsSL https://dev.jeffpelton.com/_site/devsite.cjs -o scripts/devsite.cjs.

Credentials

Publishing uses the IAM user dev-jeffpelton-publisher. It can read and write objects in the dev.jeffpelton.com bucket and invalidate its CloudFront distribution, and nothing else. It's looked up in this order:

  1. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY in the environment (CI),
  2. AWS_PROFILE, if set,
  3. the local dev-jeffpelton profile in ~/.aws/credentials (Jeff's machine).

If none of these exist, devsite stops and says so. Only Jeff can hand out the key, so ask him rather than working around it.

Safety rails

  • Name ownership. Each publish records the git repo it came from (CI_PROJECT_URL in CI). Publishing the same name from a different repo is refused unless you pass --force, so two projects can't silently overwrite each other.
  • Undo. The bucket keeps old versions of every file for 30 days, so a bad publish or an unpublish can be rolled back.
  • Reserved names. Paths used by the index site itself (_site, notes, hosting, 404.html, ...) can't be used as site names.
  • Shared origin (path mode). Path-mode sites all share the origin dev.jeffpelton.com, so localStorage, IndexedDB and cookies are shared between them. Prefix storage keys with the site name (voxel-golf:settings). Use subdomain when a site needs its own origin. Either way, never put secrets in a site.

How the index finds sites

Every site's files live under <name>/ in the same S3 bucket, behind the same CloudFront distribution, whatever its mode. A CloudFront function maps each request onto that folder, and reads the subdomain/spa flags from a CloudFront key-value store that publish updates when they change. publish also writes a manifest to /<name>/devsite.json in the bucket (not publicly readable) and updates /_site/sites.json, the public list of listed sites. The index page is built from that list and re-fetches it in the browser, so a new site appears right away without rebuilding this site. devsite list shows every site, unlisted ones included, with its mode and source repo.

Write-ups are notes in the jeff/dev.jeffpelton.com repo (content/notes/YYYY-MM-DD-<slug>.md, frontmatter title, description, optional site: <name>). Pushing to main deploys the index site with them.