KeeWeb Deploy Package
Self-hosted KeeWeb v1.18.7 password manager at kw.igg.ms. Download-based build (not from source).
WHERE TO LOOK
Section titled “WHERE TO LOOK”| 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 |
BUILD FLOW
Section titled “BUILD FLOW”src/build.tsdownloadsKeeWeb-{version}.html.zipfrom GitHub Releases- Zip cached in
.cache/(skipped if already present) dist/cleared and rebuilt every runDROPBOX_APP_SECRETenv var injected intodist/config.jsonat.settings.dropboxSecretconfig/kw.igg.ms.confcopied todist/config/kw-security-headers.confcopied todist/
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 FLOW
Section titled “DEPLOY FLOW”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 → reloadOn 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.
SERVER
Section titled “SERVER”- User:
deploy-kw(uid 997,www-datagroup) - 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+sfor group-write persistence
CLI COMMANDS
Section titled “CLI COMMANDS”The packages/cli/ provides wrapper commands for keeweb operations:
bunx @marcusrbrown/infra keeweb status— HTTP check, last deploy, content hash comparisonbunx @marcusrbrown/infra keeweb deploy— triggers GitHub Actions workflow or local deploy.shbunx @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.
ANTI-PATTERNS
Section titled “ANTI-PATTERNS”- Never commit real
dropboxSecret— template stays empty, CI injects from env. - Never run
deploy.shwithout building first — it validatesdist/contents. - Never deploy nginx config without
--nginxflag — content-only is the safe default. rsyncuses--no-times --no-permsto avoid permission errors with the deploy user.- In CI,
DROPBOX_APP_SECRETmust be set and non-empty —build.tsthrows. Locally, empty secret is tolerated (Dropbox storage disabled).