Skip to content

KeeWeb Deploy Package

Self-hosted KeeWeb v1.18.7 password manager at kw.igg.ms. Download-based build (not from source).

Task Location Notes
Change KeeWeb version src/build.ts Update KEEWEB_VERSION constant
Modify nginx config config/kw.igg.ms.conf Requires --nginx flag to deploy
Change app config template config/config.json Never put real secrets here
Modify deploy behavior deploy.sh Content-only by default
Re-provision server user server/setup-deploy-user.ts Run via bun run locally, SSHes into server
Build tests src/build.test.ts Colocated alongside build.ts
  1. src/build.ts downloads KeeWeb-{version}.html.zip from GitHub Releases
  2. Zip cached in .cache/ (skipped if already present)
  3. dist/ cleared and rebuilt every run
  4. DROPBOX_APP_SECRET env var injected into dist/config.json at .settings.dropboxSecret
  5. config/kw.igg.ms.conf copied to dist/
  6. config/kw-security-headers.conf copied to dist/

Critical: config/config.json (template) is never modified. Secret only goes into dist/config.json.

Integrity: SHA-256 of the release zip is verified on every build (cache hit and fresh download) via Bun.CryptoHasher('sha256'). Expected hash is the EXPECTED_SHA256 constant in src/build.ts (sourced from KeeWeb’s official Verify.sha256). Mismatch deletes the corrupt file and aborts.

Testability: build.ts exports individual build helpers (including ensureCachedArchive, verifyArchiveHash, extractArchive, and writeConfigWithSecret) and guards its top-level execution with import.meta.main so tests can import them without triggering a build. The cache, extraction, config-injection, and copy helpers accept path overrides for isolated tests. Fixtures in src/__fixtures__/ (e.g., test-archive.zip) stand in for real downloads.

deploy.sh [--nginx]
├── Validates dist/index.html and dist/config.json (plus both nginx files with --nginx)
├── Backs up the current site into the deploy user's backups directory
├── rsync dist/ → deploy-kw@box.heatvision.co:/home/user-data/www/kw.igg.ms/ (excludes nginx files)
├── [--nginx] scp site config and security headers snippet → deploy user's staging directory
└── ssh: sudo /usr/local/bin/kw-deploy-activate [--nginx]
├── Sets site ownership and permissions (775 + setgid)
└── [--nginx] backs up/installs staged configs → nginx -t → reload

On nginx -t failure, the activation helper restores existing configuration backups and exits nonzero. This does not roll back site content, and a reload failure does not take the configuration-restore path. The deploy user stages files; only the privileged activation helper installs nginx configuration.

  • User: deploy-kw (uid 997, www-data group)
  • Site path: /home/user-data/www/kw.igg.ms/
  • Sudo scope: only /usr/local/bin/kw-deploy-activate
  • Backup dir: /home/deploy-kw/backups/
  • Activation: chmod -R 775 + find -type d -exec chmod g+s for group-write persistence

The packages/cli/ provides wrapper commands for keeweb operations:

  • bunx @marcusrbrown/infra keeweb status — HTTP check, last deploy, content hash comparison
  • bunx @marcusrbrown/infra keeweb deploy — triggers GitHub Actions workflow or local deploy.sh
  • bunx @marcusrbrown/infra keeweb deploy --local — runs deploy.sh directly (requires ssh-agent)
  • bunx @marcusrbrown/infra keeweb open — opens https://kw.igg.ms/ in default browser (fire-and-forget)

See packages/cli/AGENTS.md for CLI conventions.

  • Never commit real dropboxSecret — template stays empty, CI injects from env.
  • Never run deploy.sh without building first — it validates dist/ contents.
  • Never deploy nginx config without --nginx flag — content-only is the safe default.
  • rsync uses --no-times --no-perms to avoid permission errors with the deploy user.
  • In CI, DROPBOX_APP_SECRET must be set and non-empty — build.ts throws. Locally, empty secret is tolerated (Dropbox storage disabled).