A free old-web homepage host. Accidents welcome. Every member gets name.yourdomain for a static
site, with a file manager, an in-browser editor, a hit counter, a guestbook and a webring link.
Accounts. Signup with email confirmation and an optional Cloudflare Turnstile captcha. Log in with site name or email. Password reset, email change (confirmed by link) and account deletion; a deleted site's name is held for 90 days.
Building a site.
- Four starter layouts (
templates/), picked at signup and each styled from one block of colour and font variables. Ifindex.htmlgoes missing, the dashboard offers to put a starter back. - File manager: drag-and-drop uploads with a progress bar, folders, rename and move, zip import, and a one-click download of the whole site as a zip. Uploads can shrink big photos on the server (sharp) and strip their camera details, and the dashboard lists links and images that point at missing files.
- Code editor (CodeMirror, served by PuppyPad itself) with find-and-replace, tag autocomplete and a sandboxed live preview. New pages start from the
member's starter layout. An image picker inserts
<img>with the picture's width and height. - Style editor (
/dashboard/style): colours, font, borders, page width and cursor, with presets and a live preview. It writespuppypad.cssand leaves any CSS below its block alone. - Limits from
.env:QUOTA_MBof space per member (500 by default),MAX_FILE_MBper file,ZIP_MAX_MBper import andBANDWIDTH_MBserved per day. File types follow a fixed allowlist (src/util.js). RaisingQUOTA_MBgrows every site; lowering it only applies to new signups. - Optional supporter tier through Stripe (
STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET,STRIPE_PRICE_ID; hidden while the keys or both prices are empty). An optionalSTRIPE_PRICE_ID_ANNUALadds a yearly price offered next to the monthly one. Supporters getSUPPORTER_QUOTA_MB(2000) andSUPPORTER_MAX_FILE_MB(25), any file type, longer history, up to 5 sites per login, a rainbow frame and star by their name, and a first look at widgets markedearly./dashboard/supportopens Stripe Checkout and the Customer Portal;POST /stripe/webhooksetsusers.supporter_until. When it lapses nothing is deleted: uploads wait until the site is under the free limits. Admins can grant it by hand on/admin.
Serving. Each site is served on its own subdomain, with clean URLs (/about serves about.html)
and an optional custom not_found.html. Members see views per page per day and the sites visitors
came from for the last 30 days, counted without cookies or IP addresses. A member can rename their
site once every RENAME_DAYS (30 by default); the old address redirects for the 90 days it is held.
Every save of a page or other text file is kept in a git repository per site under data/history for
HISTORY_DAYS (30; SUPPORTER_HISTORY_DAYS, 365, for supporters), so a member can look at an old version,
put it back, or bring back a deleted file from the dashboard. Pictures are not kept. Built-in widgets: /_hw/counter.svg, /_hw/guestbook
(the owner can delete entries, and is emailed about new ones right away, in a daily digest or not at
all, and themed with ?theme=), /_hw/updated.svg, /_hw/status.svg, webring prev/next/random links,
88×31 buttons, stamps and two effect scripts, all handed out as snippets on /dashboard/widgets. The
style editor also sets a tiling background from src/assets/bg/ or the member's own pictures.
HTTP API. A member makes an API key on /dashboard/api (with their password; only its sha256 is
kept, and a password change or reset switches it off). With Authorization: Bearer <key>:
GET /api/site (address, space, file count, allowed types), GET /api/files (with a sha256 per file),
GET /api/file?path= (one file's bytes), POST /api/upload (multipart files, up to 20, the filename
may include folders) and POST /api/delete (path, or up to 100 paths). Uploads go through the
dashboard's name, type, quota and phishing checks; 120 requests a minute per member.
CLI and deploy Action. npx @puppypad/cli push uploads a folder's new and changed files (--delete
mirrors it, --dry-run previews), and pull downloads the site; see cli/README.md.
The same CLI runs as a GitHub Action (uses: DeRusto/puppypad@main, action.yml) to deploy a
repository on every push. Releases publish it to npm as @puppypad/cli through npm trusted publishing.
Community. The Explore page shows a screenshot of every site, sortable by recently updated,
newest, most followed and most visited, with a search by site name or tag (members add up to 5 tags).
Members can follow sites and read a feed of their updates, which names the files each update changed,
and every site has a profile page (/site/name). Atom feeds: /site/name/feed.xml per site and
/feed.xml for recently updated sites. A new site joins Explore, the home page, the
webring and /random after its first edit, once it is NEW_SITE_HOURS old (24 by default). A
member can hide their site from all of these and from search engines. Members comment on profiles
and on feed updates, like updates, and block members they don't want to hear from. /notifications
lists new followers, comments and likes, with optional email for each and an opt-in weekly digest of
followed sites. Admins set staff picks and a site of the week for the home page from /admin.
Member sites without a favicon get PuppyPad's, and pages without an og:image get the site's
screenshot for link previews.
Accounts. Members can turn on two-factor login (any TOTP authenticator app, with 10 recovery codes) and log out everywhere from their profile page.
Moderation. A public report form (linked from the default 404/410 pages), an /admin queue,
take down / restore / delete, signup IPs and a log of every moderator action. HTML that looks like
phishing is flagged into the queue automatically. Rate limits on signup, login, reports and
guestbooks, honeypot fields, and unconfirmed accounts are purged after 3 days.
/healthz answers for an uptime monitor.
-
In Cloudflare DNS, point
A example.comandA *.example.comat the server, set to DNS only (grey cloud). Create an API token with the "Edit zone DNS" template for that zone; Caddy uses it to get one wildcard certificate. -
Install Docker (with the compose plugin),
curl,jq,rsyncandcron, then install the newest release:sudo mkdir -p /srv/puppypad && sudo chown "$USER" /srv/puppypad && cd /srv/puppypad curl -fsSL https://github.com/DeRusto/puppypad/releases/latest/download/install.sh | shThat unpacks the release, creates
.envand.env.caddyfrom the examples, and adds the upgrade watcher (every minute) and the nightly backup (03:15) to your crontab. Fill in.env(BASE_DOMAIN, ACME_EMAIL, ADMIN_EMAILS, SMTP_*, SHOT_TOKEN) and.env.caddy(CF_API_TOKEN, which only the Caddy container reads), thendocker compose up -d. -
Sign up with an email you put in
ADMIN_EMAILSand confirm it. Until SMTP is set, the confirmation link is indocker compose logs app. -
Open
/adminwhen logged in as that member.
Everything lives in ./data (SQLite database plus sites/). Back that folder up.
To move a server that runs from a git checkout onto releases, run the same curl ... | sh line in
the checkout with the app running. It treats this as an upgrade (below) and leaves .env,
.env.caddy, data/ and backups/ as they are. Delete any docker-compose.override.yml first.
scripts/backup.sh takes a consistent copy of the database while the app runs and brings one copy
of it, every member's files, the screenshots and the file history (data/history) up to date in
backups/latest with rsync, so each night only writes what changed. Older versions of members' pages
come from their file history rather than from older backups. Set BACKUP_REMOTE to an
rclone remote to mirror it off the server too: the remote keeps latest/
plus whatever each night changed or deleted in old/<date>/, for 14 days. Leave room for one more
copy of data/ on the server's disk: once less than 5% is free, /healthz fails and uploads are
turned away. The installer schedules it every night at 03:15, logging to backups/backup.log.
To restore: docker compose stop app, delete data/puppypad.db-wal and data/puppypad.db-shm
(left over, they would be replayed onto the restored database and corrupt it),
rsync -a --delete backups/latest/ data/ (after rclone copy <remote>/latest backups/latest if the
server's copy is gone), rename data/backup.db to data/puppypad.db, and docker compose start app.
A file as it was before a given night is in the remote's old/<that night>/.
docs/launch-checklist.md has a restore test that doesn't touch the live data.
Servers run published releases, not the source tree. Publishing a GitHub release tagged vX.Y.Z
runs .github/workflows/release.yml, which tests the code, pushes the app, shots and Caddy images to
ghcr.io/derusto/puppypad-{app,shots,caddy}:vX.Y.Z, and attaches the deploy bundle, install.sh
and SHA256SUMS to the release. Those three packages must be public (GitHub profile > Packages) or
servers can't pull them.
scripts/install.sh both installs and upgrades: with no argument it moves to the newest release,
and scripts/install.sh v1.2.3 moves to a given one (older ones too). An upgrade:
- downloads the release bundle, checks it against
SHA256SUMS, and hands over to that release's owninstall.sh(except when the release expects an older database schema; see below) - pulls the new images by the digests the bundle records, so re-pushing a tag can't change what a release runs
- runs
scripts/backup.sh - puts the release's files in place, sets
PUPPYPAD_VERSIONand the image digests in.env, and runsdocker compose up -d - waits for
/healthzand for every container to stay running, and puts the previous files and version back if it doesn't come up.VERSIONchanges only once this passes, so an interrupted upgrade is simply tried again.
An upgrade replaces docker-compose.yml, Caddyfile and scripts/ with the release's copies, so
local changes there are lost (the last replaced copies sit in .upgrade/prev.tar until the next
upgrade). Put compose changes (a bigger mem_limit, another port) in docker-compose.local.yml
and add COMPOSE_FILE=docker-compose.yml:docker-compose.local.yml to .env: docker compose then
loads both, and upgrades never touch it. Don't use docker-compose.override.yml; the installer
refuses it, since a source checkout uses that name to build images from source.
Every download and pull has a time limit.
Database schema. The database records a schema number (src/schema.js), and each release bundle
says which one it expects in SCHEMA (none means 0). Changes that older code can't run with, like a
renamed column, come with a step back. When the installer moves to a release with a lower schema,
whether going back after a failed upgrade or moving to an older release on purpose, it stops the app
and runs the steps back with the image of the release it leaves, before the older release starts.
Moving to an older schema, the installer keeps control instead of handing over to the older
release's installer, which doesn't know the steps. The newer app re-applies them when it starts
again. The backup from step 3 stays in backups/latest until the next nightly backup.
From a git checkout there's no installer. Before checking out an older version, put the database back to that version's schema (0 for every release before this mechanism) with the newer code still in place. Back up first. To bring back a newer backup for older code, do the restore above but leave the app stopped, then run only the last two commands:
scripts/backup.sh
docker compose stop app
docker compose run --rm --no-deps app node src/schema.js down 0
From /admin. The "Server version" box at the bottom of /admin shows the running release, the
newest one with its notes, and a button that runs the upgrade above. The app never upgrades itself:
it runs in a container with no Docker access and no credentials, and only leaves a request in
data/upgrade/. scripts/upgrade-watch.sh, run every minute from cron on the host, picks it up and
only accepts "check" or the newest release's tag, so a compromised app can at most ask for the
release you published. It checks GitHub every UPGRADE_CHECK_MINUTES (60 by default) and logs to
.upgrade/watch.log, with the full output of the last upgrade in .upgrade/last.log.
The app (uid 1000 in its container) and the watcher both write to data/upgrade/, which is
group-writable. If the user running the watcher isn't uid 1000 or root, the installer prints the one
sudo chown it needs.
Confirmation mail lands in spam unless the domain vouches for your mail provider.
docs/launch-checklist.md has the exact records for puppypad.org. In general, in Cloudflare DNS for
the domain, add the records your provider gives you:
- SPF: one TXT record on the domain itself, e.g.
v=spf1 include:<provider's domain> ~all. Merge providers into one record if you already have one. - DKIM: the TXT or CNAME records the provider generates (usually under
..._domainkey). - DMARC: a TXT record named
_dmarc, starting withv=DMARC1; p=none; rua=mailto:you@yourdomain. Move top=quarantineonce reports show your mail passing.
Then sign up with a Gmail address and check that the confirmation arrives in the inbox.
npm install
BASE_URL=http://localhost.test:3000 ADMIN_EMAILS=me@example.com node src/server.js
Add 127.0.0.1 localhost.test me.localhost.test to your hosts file to see a member site.
Screenshots: cd shots && npm install, then run APP_URL=http://localhost:3000 SHOT_TOKEN=x node worker.js
with the app started with the same SHOT_TOKEN (needs a Playwright Chromium install).
In the source tree, docker-compose.override.yml makes docker compose up -d --build build the
images locally instead of pulling them.
npm test runs the suite in test/. GitHub Actions runs it on every push, along with npm audit
and a check that the Caddyfile is valid.
- Mail: public signups need real SMTP (any transactional mail provider works). Without it nobody can confirm.
- Certificates: Caddy (built from
caddy/Dockerfilewith the Cloudflare DNS plugin) gets one*.yourdomaincertificate through a DNS challenge, so new member sites never wait on a certificate. Keep the DNS records grey-clouded: if you turn on Cloudflare's proxy, every visitor arrives from a Cloudflare IP, and the per-IP rate limits need to read the real address fromCF-Connecting-IPfirst. - Cookies: member pages run their own JavaScript on subdomains of your main domain. The login cookie is host-only with the
__Host-prefix, so member sites cannot read or overwrite it. Serving member sites from a separate domain is stronger still, and is what the big hosts do. - Rules: edit the rules page in
src/views.js. As the operator you are the one who gets the takedown notices, so keepABUSE_EMAILmonitored. If you are in the US, look into registering a DMCA agent. - Supporter tier: before setting the Stripe keys, read the "Supporter terms" on
/rulesand the Stripe line on/privacy(both appear once the keys are set) and make them match what you sell. In the Stripe Dashboard: turn on the Customer Portal with cancellation at the end of the period, turn on Smart Retries and the failed-payment emails (Billing > Revenue recovery), and give the product the "digital services" tax category with your head office address so Stripe Tax's free threshold monitoring warns you before you owe sales tax anywhere. - Captcha: set
TURNSTILE_SITE_KEYandTURNSTILE_SECRET_KEY(Cloudflare Turnstile) before opening signups. Without them only the honeypot and rate limits stand in the way of bots. - Phishing: saving or uploading an HTML page with a password field, a card-number field or a big brand name in its title puts the site in the
/adminqueue as an "Auto-flag" report and emailsABUSE_EMAIL. The site stays online until a moderator looks. - Public Suffix List: see
docs/public-suffix-list.md. - Screenshots: the
shotscontainer opens every member page in headless Chromium. It blocks requests to IP addresses and internal hostnames, but for defense in depth also firewall that container from your private network and the cloud metadata address (169.254.169.254). - Disk: worst case is members x
QUOTA_MB(500 MB by default, so an 80 GB disk holds about 100 full sites). Add a volume before signups grow past that, keep a disk alert at 80%, or lower the quota.
PuppyPad is free software, licensed under the GNU Affero General Public License v3 — Copyright © 2026 Brandon Douglas Winterton. Run it, modify it, share it; if you run a modified version as a public service, publish your changes too.