Hetzner Bootstrap

Date: 2026-05-05

Objective

Define the first server bootstrap gate for the Hetzner rebuild.

This is not an auto-install script. It is a readiness checklist for the server before source sync, Docker builds, env validation, and health checks.

What Was Added

• scripts/hetzner-bootstrap.mjs Read-only host bootstrap checker.
• package.json scripts:
  • hetzner:bootstrap:plan
  • hetzner:bootstrap
  • hetzner:bootstrap:check

Bootstrap Commands

Print the bootstrap plan:

npm run hetzner:bootstrap:plan

Inspect the current host:

npm run hetzner:bootstrap

Run the strict bootstrap gate:

npm run hetzner:bootstrap:check

What The Gate Checks

The bootstrap gate checks:

• native Linux x64/amd64 host;
• Node.js 20+;
• at least 8 GiB RAM, with 16 GiB recommended;
• npm;
• Docker Engine;
• Docker Compose;
• rsync;
• curl;
• tar;
• gzip;
• openssl;
• lsof;
• Docker daemon availability;
• whether the current user can reasonably run Docker.

Server Preparation Order

Use this sequence on Hetzner:

1. Provision the server.
2. Create or choose a non-root deploy user.
3. Install Node.js 20+, npm, Docker Engine, Docker Compose, rsync, curl, tar, gzip, openssl, and lsof.
4. Make Docker usable by the deploy user through the docker group or an intentional sudo policy.
5. Configure firewall policy:
   • allow SSH from trusted admin IPs;
   • allow 80/tcp and 443/tcp when the reverse proxy is ready;
   • keep internal staging ports private unless intentionally debugging.
6. Sync the project source.
7. Run npm install.
8. Run npm run hetzner:bootstrap:check.
9. Run npm run hetzner:host:check.

Only after those pass should the staging env files, image builds, and health checks be treated as the next milestone.

Current Verification Evidence

• npm run hetzner:bootstrap:plan prints the server bootstrap order.
• npm run hetzner:bootstrap runs locally and reports why this Mac is not the target host.
• npm run hetzner:bootstrap:check is expected to fail locally because this Mac is not native Linux x64/amd64 and does not have Docker Compose in the local Docker CLI.

Known Blockers

• No Hetzner server bootstrap evidence exists yet.
• Exact installation commands depend on the chosen Linux image and should be run from that server's maintained package/vendor instructions.