--- docType: deployment-procedure version: 1.0 templateVersion: 1 --- # Deployment Procedure — Sanduhr für Claude (Windows v2) > **Context:** Sanduhr für Claude is a desktop widget, not a web service. There is no server to > deploy to. "Deployment" means building a signed-unsigned `.exe` installer and publishing it to > GitHub Releases so end users can download and install it. Concepts like canary deploys, > blue/green, SLA uptime targets, database migrations, and traffic shifting are **N/A** — this is > an end-user desktop install. --- ## Environments There is exactly **one environment**: the end user's Windows machine. | Environment | Description | |---|---| | End-user machine | The user's Windows PC where the `.exe` installer is run | There is no staging environment, no production server, and no cloud deployment. The CI runner (`windows-latest` GitHub Actions) is a build environment only — it produces the artifact and disappears. It is not a deployment target. **Supported OS:** - Windows 10 21H2 or later (minimum) - Windows 11 22H2 or later (recommended — required for full Mica glass backdrop) **Architecture:** 64-bit only (`ArchitecturesInstallIn64BitMode=x64` per Inno Setup config). --- ## Prerequisites ### To run the installed app (end user) - Windows 10 21H2+ or Windows 11 22H2+ - A Claude Pro, Team, or Enterprise subscription - A `claude.ai` session cookie (`sessionKey`) — retrieved from browser DevTools → Application → Cookies on claude.ai - Internet access to `claude.ai` - No Python or other runtime required — the `.exe` bundles everything via PyInstaller ### To build the installer from source (developer) - Python 3.11 (pinned — CI uses `python-version: "3.11"`) - Inno Setup 6.2.2 (installed via `choco install innosetup --version=6.2.2 -y` in CI; or manually from https://jrsoftware.org/isdl.php) - PowerShell 5.1+ (included in Windows 10/11) - Git **Python dependencies (runtime):** - PySide6 == 6.8.0.2 - cloudscraper == 1.2.71 - keyring == 25.5.0 - requests == 2.32.3 **Python dependencies (build/test only):** - pyinstaller == 6.11.1 - pytest == 8.3.3 - pytest-qt == 4.4.0 - pytest-cov == 5.0.0 - requests-mock == 1.12.1 ### GitHub Actions (automated release builds) - `windows-latest` runner (provided by GitHub) - `contents: write` permission on the repo (configured in `windows-release.yml`) - `softprops/action-gh-release@v2` action (handles GitHub Releases upload) --- ## Build Process The build pipeline is orchestrated by `windows/build.ps1` and runs in two stages: ### Stage 1 — PyInstaller (Python → standalone exe folder) ```powershell cd windows pyinstaller sanduhr.spec --clean --noconfirm ``` - Entry point: `src/sanduhr/__main__.py` - Output: `windows/dist/Sanduhr/` (one-folder bundle — `Sanduhr.exe` + Qt DLLs + Python runtime) - Icon embedded: `icon/Sanduhr.ico` - Version metadata embedded: `version_info.txt` (FileVersion, ProductVersion, CompanyName, etc.) - Mode: windowed (no console), 64-bit - Excluded modules (to reduce size): `PySide6.QtWebEngineCore`, `PySide6.QtWebEngineWidgets`, `PySide6.QtMultimedia`, `PySide6.QtQuick3D`, `PySide6.QtNetworkAuth`, `PySide6.QtPdf`, `PySide6.QtBluetooth`, `PySide6.QtSerialPort` - Hidden imports explicitly declared: `cloudscraper`, `keyring.backends.Windows`, `PySide6.QtSvg` ### Stage 2 — Inno Setup (folder bundle → single `.exe` installer) ```powershell & "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" "installer/Sanduhr.iss" ``` - Input: `windows/dist/Sanduhr/*` - Output: `windows/build/Sanduhr-Setup-v{version}.exe` - Compression: `lzma2/ultra64` solid - Install location: `{autopf}\Sanduhr` (respects Program Files for the architecture) - Privilege level: `lowest` (no UAC elevation required by default; user can elevate via dialog) - Installer tasks offered: Start Menu shortcut (checked), Desktop shortcut (unchecked), Launch at login (unchecked) - Autostart implemented via `HKCU\...\Run` registry key (user scope, no admin required) ### Debug build variant ```powershell ./build.ps1 -DebugBuild ``` Temporarily patches `sanduhr.spec` to set `console=True` so tracebacks are visible in a console window. The patched spec (`sanduhr-debug.spec`) is deleted after the build. ### Build scripts | Script | Purpose | |---|---| | `windows/build.ps1` | Full pipeline orchestrator | | `windows/sanduhr.spec` | PyInstaller configuration | | `windows/installer/Sanduhr.iss` | Inno Setup installer script | | `windows/version_info.txt` | PE version metadata embedded into `Sanduhr.exe` | --- ## Environment Setup ### For end users — no setup required The installer handles everything. There are no environment variables, config files, or secrets to provision before installing. On first launch, Sanduhr prompts the user to paste their `sessionKey` (retrieved from claude.ai DevTools → Application → Cookies → `sessionKey`). The credential is stored immediately in **Windows Credential Manager** under service name `com.626labs.sanduhr`. No plaintext credential files are written. **Per-user data directories (created automatically at runtime):** | Path | Contents | |---|---| | `%APPDATA%\Sanduhr\` | Settings (`config.json`), usage history (`history.json`) | | Windows Credential Manager | `sessionKey`, optional `cf_clearance` (Cloudflare bypass cookie) | ### For developers building from source ```powershell cd windows python -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements-dev.txt pip install -e . ``` No environment variables are required to build or run the widget in development mode. ### Secrets and credentials There are **no server-side secrets** to manage. The only credentials are user-owned: - `sessionKey` — the user's own claude.ai session cookie, entered at first run - `cf_clearance` — optional Cloudflare bypass cookie, also user-owned These live in the user's Windows Credential Manager and are never transmitted to any 626Labs server. --- ## Testing Before Deploy ### Automated gate (runs on every push + on release tag) The CI workflow (`.github/workflows/windows-ci.yml`) and the release workflow both run the pytest suite before any build proceeds: ```bash pytest --cov=sanduhr --cov-report=term-missing ``` The release workflow runs `pytest` (without coverage flags) as a hard gate — if any test fails, the workflow stops and no installer is built or uploaded. **Test stack:** - pytest 8.3.3 - pytest-qt 4.4.0 (Qt widget tests) - pytest-cov 5.0.0 (coverage) - requests-mock 1.12.1 (HTTP mocking) ### Manual release checklist (run before every tagged release) Full checklist defined in `windows/TEST_PLAN.md`. Estimated time: 20 minutes. Run on a **clean Windows 11 22H2+ VM** with no prior Sanduhr install. **Checklist summary:** 1. **Fresh install** — installer wizard, SmartScreen bypass, post-install launch, first-run setup dialog, sessionKey entry, usage bars visible within ~5 seconds 2. **v1 upgrade** — install over an existing v1 deployment; verify credential migration, history preservation, old config cleanup 3. **Theme rendering** — all 5 themes (Obsidian, Aurora, Ember, Mint, Matrix) compared against reference screenshots 4. **Mica / Win10 fallback** — translucent backdrop on Win11 22H2+; solid fallback on Win10, no crash 5. **Controls** — Pin, compact mode, Key dialog, Refresh, context menu, drag-to-move, position persistence 6. **Session expiry** — bad sessionKey → error state → recovery on valid key 7. **Cloudflare block** — blocked host → "Cloudflare" error → cf_clearance entry → recovery 8. **Autostart** — install with "Launch at login" checked; verify sign-in launch; verify uninstall cleans registry 9. **Uninstall** — with and without "Also remove my settings and history" checkbox; verify Credential Manager cleanup **Exit criterion:** All checklist items must pass before tagging the release. --- ## Deployment Steps Deployment is fully automated once a git tag is pushed. Manual steps are limited to tagging and verifying the resulting GitHub Release. ### Step 1 — Complete manual test checklist Run all items in `windows/TEST_PLAN.md` on a clean Win11 22H2+ VM. Do not tag until all pass. ### Step 2 — Update version references Before tagging, ensure version numbers are consistent across: - `windows/installer/Sanduhr.iss` — `#define MyAppVersion` - `windows/RELEASE_NOTES.md` — update release notes for the new version > Version sync is automated. `build.ps1` reads the version from > `pyproject.toml`, rewrites `version_info.txt` in place, and passes > `/DMyAppVersion=X.Y.Z` to ISCC so the installer filename + embedded > .exe metadata always match. Bump `pyproject.toml` once and tag. ### Step 3 — Tag the release Tag format: `v{major}.{minor}.{patch}-windows` ```bash git tag v2.0.0-windows git push origin v2.0.0-windows ``` The tag push triggers `.github/workflows/windows-release.yml` automatically. ### Step 4 — Automated release pipeline (GitHub Actions) The workflow runs on `windows-latest` and performs these steps automatically: 1. Check out the repository 2. Set up Python 3.11 with pip cache 3. `pip install -r requirements-dev.txt && pip install -e .` 4. `choco install innosetup --version=6.2.2 -y` 5. `pytest` (gate — failure aborts) 6. `./build.ps1` (PyInstaller → Inno Setup → `build/Sanduhr-Setup-v{version}.exe`) 7. Extract version from tag name (strips `v` prefix and `-windows` suffix) 8. Upload `windows/build/Sanduhr-Setup-v{version}.exe` to GitHub Releases with `windows/RELEASE_NOTES.md` as the release body Estimated CI runtime: ~10–15 minutes (dominated by Chocolatey install and PyInstaller bundling). ### Step 5 — User distribution Users download the `.exe` from the GitHub Releases page: `https://github.com/estevanhernandez-stack-ed/Sanduhr_f-r_Claude/releases` **User install flow:** 1. Download `Sanduhr-Setup-v{version}.exe` 2. SmartScreen warning appears — click **More info** → **Run anyway** (expected for unsigned apps) 3. Step through the installer wizard 4. Choose shortcut and startup options 5. Launch Sanduhr from Start Menu on wizard completion 6. On first run: paste `sessionKey` from claude.ai DevTools → Application → Cookies --- ## Post-Deployment Checks ### Verify the artifact exists on GitHub Releases 1. Navigate to `https://github.com/estevanhernandez-stack-ed/Sanduhr_f-r_Claude/releases` 2. Confirm the new release entry is present with the correct tag (`v{version}-windows`) 3. Confirm `Sanduhr-Setup-v{version}.exe` is listed as a release asset 4. Confirm release body matches `windows/RELEASE_NOTES.md` content 5. Download the `.exe` and verify it is not zero-byte (workflow sets `fail_on_unmatched_files: true` so a missing artifact would have failed the workflow, but confirm anyway) ### Verify installer runs on a clean machine 1. On a clean Windows 11 22H2+ VM (or a freshly reset test machine): - Run `Sanduhr-Setup-v{version}.exe` - SmartScreen warning appears → More info → Run anyway - Installer completes without errors 2. Sanduhr launches after install 3. First-run dialog appears; enter a valid `sessionKey`; usage bars appear within ~5 seconds ### Verify PE version metadata Right-click `Sanduhr.exe` (in the install directory) → Properties → Details tab. Confirm: | Field | Expected value | |---|---| | File description | `Sanduhr für Claude -- Claude.ai Usage Tracker` | | File version | `{major}.{minor}.{patch}.0` | | Product name | `Sanduhr für Claude` | | Product version | `{major}.{minor}.{patch}.0` | | Company | `626Labs` | | Original filename | `Sanduhr.exe` | ### Verify Credential Manager integration After entering a sessionKey, open Windows Credential Manager → Windows Credentials. Confirm an entry named `com.626labs.sanduhr` is present. --- ## Rollback Procedure Sanduhr has no server-side state to roll back. "Rollback" means: 1. Directing users to reinstall the previous released version 2. Optionally removing the bad release from GitHub There are no database migrations, no feature flags, and no staged rollout to undo. ### If a bad release is caught before user distribution 1. Delete the GitHub Release (or mark it as a pre-release/draft to hide it from the default download) 2. Delete the tag: ```bash git tag -d v{bad-version}-windows git push origin :refs/tags/v{bad-version}-windows ``` 3. Fix the issue on `windows-native` 4. Retag with the corrected commit (or bump to a patch version) ### If users have already downloaded and installed the bad version 1. Identify the last known-good release on the GitHub Releases page 2. Post a notice on the Releases page or as a new release pointing users to the prior version 3. Users reinstall by downloading the previous `Sanduhr-Setup-v{prior-version}.exe` from GitHub Releases and running it over the existing install (the installer handles in-place upgrade/downgrade) 4. User settings in `%APPDATA%\Sanduhr\` and Credential Manager entries are preserved across reinstalls (the installer uses `ignoreversion` for files) 5. If a credential or config migration was the source of the bug, users may need to clear `%APPDATA%\Sanduhr\` manually or re-enter their sessionKey ### User data safety during rollback - `%APPDATA%\Sanduhr\` is **not** touched by the installer on install or uninstall (unless the user explicitly checks "Also remove my settings and history" during uninstall) - Windows Credential Manager entries persist across reinstalls - There is no risk of data loss from reinstalling a prior version --- ## Notes on Template Sections Not Applicable to a Desktop App The following standard deployment-procedure sections were intentionally omitted or marked N/A because they apply to hosted services, not a desktop distribution: | Template concept | Disposition | |---|---| | Staging / production environments | N/A — one artifact, one destination (user's disk) | | Canary deploy / blue-green | N/A — no server, no traffic to shift | | Database migrations | N/A — no database | | Service restarts / health checks | N/A — no service; app is a user-launched process | | SLA / uptime targets | N/A — no hosted service; availability is the user's machine | | Traffic shifting / load balancer | N/A | | Rollback of server state | N/A — rollback = reinstall prior installer | | Environment variables for production | N/A — no server config; only user credentials in Credential Manager |