From 312e72ff54e5e22065fa7a857d3231b157246a50 Mon Sep 17 00:00:00 2001 From: PointStar Date: Mon, 11 May 2026 17:41:23 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20add=20AUTO-UPDATE-SETUP.md=20=E2=80=94?= =?UTF-8?q?=20Hebrew=20runbook=20for=20the=20infra=20team?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step-by-step infrastructure setup guide covering everything needed to turn the ClickOnce auto-update pipeline live: 1. Architecture diagram 2. Prerequisites checklist 3. Setup steps: - Windows Build Runner provisioning + Gitea Actions registration - Self-signed code-signing cert generation - Infisical secret storage - Gitea Actions secrets wiring - nginx config on platform.dev - GPO push of the cert to attorney machines 4. First release (v1.0.0) walkthrough 5. Day-to-day update flow (tag -> CI -> clients auto-update) 6. Monitoring, troubleshooting, rollback 7. Post-setup verification checklist 8. Periodic maintenance schedule Written in Hebrew for the Marcus-Law infrastructure team. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/AUTO-UPDATE-SETUP.md | 422 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 422 insertions(+) create mode 100644 docs/AUTO-UPDATE-SETUP.md diff --git a/docs/AUTO-UPDATE-SETUP.md b/docs/AUTO-UPDATE-SETUP.md new file mode 100644 index 0000000..1b61016 --- /dev/null +++ b/docs/AUTO-UPDATE-SETUP.md @@ -0,0 +1,422 @@ +# מערכת עדכון אוטומטי — מדריך הקמה לצוות תשתיות + +מסמך זה מסביר מה צריך להקים פעם אחת כדי שתוסף **Klear ל-Outlook** יוכל להתעדכן אוטומטית אצל כל עורכי הדין במשרד, וכיצד לשחרר עדכון חדש לאחר ההקמה. + +קהל היעד: צוות תשתיות / DevOps / IT אדמין במרקוס-לוו. +זמן הקמה משוער: 4-6 שעות פעם אחת. +שחרור עדכון חדש לאחר ההקמה: 30 שניות (push tag) + 2-3 דקות (CI). + +--- + +## 1. סקירת ארכיטקטורה + +המנגנון מבוסס על **ClickOnce** — טכנולוגיה של Microsoft שמאפשרת ל-Outlook להתקין ולעדכן תוסף VSTO מ-URL חיצוני, כמו עדכון אוטומטי של אפליקציה. + +``` +┌──────────────────┐ git tag v1.0.1 ┌─────────────────────┐ +│ מפתח (Chaim) ├──────────────────► │ Gitea repository │ +└──────────────────┘ └──────────┬──────────┘ + │ + push event│ + ▼ + ┌─────────────────────┐ + │ Windows Build Runner │ (VM ב-Coolify) + │ • restore + build │ + │ • sign DLLs │ + │ • mage → .vsto │ + └──────────┬──────────┘ + │ rsync + ▼ + ┌─────────────────────┐ + │ platform.dev │ (nginx) + │ /outlook-addin/ │ + │ ├─ OutlookAddin.vsto + │ └─ Application Files/ + └──────────┬──────────┘ + │ HTTPS poll (כל 7 ימים) + ▼ + ┌─────────────────────┐ + │ 10 מחשבי עורכי דין │ + │ ClickOnce + Outlook │ + └─────────────────────┘ +``` + +הצדדים: + +1. **CI runner** — מכונת Windows שבונה את הפרויקט, חותם את הקבצים, ומריץ את `mage.exe` שיוצר את ה-`.vsto` manifest. +2. **שרת הפצה** — nginx שמשרת קבצים סטטיים תחת `/outlook-addin/`. +3. **תעודת חתימה** — תעודת Code-Signing (self-signed) שצריכה להיות מותקנת כ-**Trusted Publisher** בכל מחשב לקוח, אחרת ClickOnce ידחה את ההתקנה. +4. **GPO** — מנגנון Active Directory להפצת התעודה אוטומטית. +5. **Infisical** — מאחסן את הסודות (cert thumbprint, SSH key, webhook URL). +6. **Mattermost** — מתריע בהצלחה/כישלון לערוץ `#git-verelasim`. + +--- + +## 2. דרישות מקדימות + +לפני שמתחילים, וודאו שיש לכם: + +- [ ] גישת Admin ל-Coolify ב-`coolify.marcus-law.co.il` (להקמת VM) +- [ ] גישת root ל-`platform.dev.marcus-law.co.il` +- [ ] תפקיד Domain Admin ב-Active Directory (להפצת GPO) +- [ ] גישת Admin ל-Gitea ב-`gitea.dev.marcus-law.co.il` +- [ ] גישת Admin ל-Infisical (פרויקט `outlook-addin`) +- [ ] Webhook ל-Mattermost בערוץ `#git-verelasim` +- [ ] שם משתמש + סיסמה של חשבון EspoCRM Admin (להנפקת API keys ללקוחות) + +--- + +## 3. שלבי הקמה (חד-פעמיים) + +### 3.1 — הקמת Windows Build Runner + +**מטרה:** VM שמריץ Gitea Actions runner ויכול לבנות פרויקטי VSTO. + +1. ב-Coolify → צור VM חדש: **Windows 11 Pro**, 4 vCPU / 8 GB RAM / 80 GB דיסק. +2. התחבר ל-VM ב-RDP. +3. התקן את הכלים הבאים (כולם בחינם): + + ```powershell + # Visual Studio Build Tools 2022 — כולל workloads נדרשים + winget install Microsoft.VisualStudio.2022.BuildTools ` + --override "--passive --wait --add Microsoft.VisualStudio.Workload.Office --add Microsoft.VisualStudio.Workload.ManagedDesktop --includeRecommended" + + # .NET Framework 4.8 Developer Pack (מספק mage.exe) + winget install Microsoft.DotNet.Framework.DeveloperPack_4 + + # Windows 10 SDK (signtool.exe) + winget install Microsoft.WindowsSDK.10.0.22621 + + # Git + winget install Git.Git + + # NuGet CLI (לפעולות restore לפרויקטי .NET Framework legacy) + choco install nuget.commandline -y + + # WSL Ubuntu — דרוש ל-rsync ב-CI workflow + wsl --install -d Ubuntu + ``` + +4. הורד את `act_runner` (Gitea Actions runner) מ-`https://gitea.com/gitea/act_runner/releases`. +5. רשום את ה-runner ל-Gitea שלכם: + + ```powershell + .\act_runner.exe register ` + --no-interactive ` + --instance https://gitea.dev.marcus-law.co.il ` + --token ` + --name "winbuild-01" ` + --labels "windows" + ``` + +6. התקן את ה-runner כשירות Windows כדי שירוץ ברקע: + + ```powershell + .\act_runner.exe daemon install + net start act_runner + ``` + +7. ודא שהוא מופיע ב-Gitea: `https://gitea.dev.marcus-law.co.il/-/admin/runners` עם status **online**. + +### 3.2 — יצירת תעודת Code-Signing + +**מטרה:** תעודה שחותמת על קבצי DLL/EXE/manifest. ClickOnce ידרוש שהיא מותקנת כ-Trusted Publisher אצל הלקוחות. + +ב-PowerShell על ה-Build Runner (כ-Administrator): + +```powershell +# יצירת תעודה לתקופה של 3 שנים +$cert = New-SelfSignedCertificate ` + -Subject "CN=Marcus-Law Klear" ` + -Type CodeSigningCert ` + -CertStoreLocation Cert:\CurrentUser\My ` + -NotAfter (Get-Date).AddYears(3) ` + -KeyAlgorithm RSA ` + -KeyLength 2048 + +# ה-thumbprint שצריך לשמור ב-Infisical +$thumbprint = $cert.Thumbprint +Write-Host "Thumbprint: $thumbprint" + +# יצא PFX (כולל המפתח הפרטי — לגיבוי, **שמור באמצעי מאובטח**) +$pfxPassword = ConvertTo-SecureString -String "" -Force -AsPlainText +Export-PfxCertificate -Cert $cert -FilePath C:\codesign.pfx -Password $pfxPassword + +# יצא רק את החלק הציבורי (CER) — זה מה שמפיצים ללקוחות +Export-Certificate -Cert $cert -FilePath C:\codesign.cer +``` + +> **חשוב**: שמור גיבוי של `codesign.pfx` + הסיסמה בכספת. אם המכונה תאבד, תצטרך אותם כדי להמשיך לחתום בעתיד באותה תעודה (אם תיצור חדשה, כל הלקוחות יקבלו "Unknown Publisher" עד שתפיץ את החדשה דרך GPO). + +### 3.3 — שמירת סודות ב-Infisical + +ב-Infisical, בפרויקט `outlook-addin`, environment `prod` (או `dev` אם אין הפרדה): + +| שם המפתח | ערך | הערה | +|---|---|---| +| `CODESIGN_THUMBPRINT` | ה-`$thumbprint` משלב 3.2 | מחרוזת hex של 40 תווים | +| `CODESIGN_PFX_BASE64` | `[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\codesign.pfx"))` | base64 של ה-PFX — לגיבוי בלבד, ה-CI לא משתמש בו ישירות | +| `CODESIGN_PASSWORD` | הסיסמה של ה-PFX | למקרה של בנייה ממכונה אחרת | +| `PLATFORM_DEV_SSH_KEY` | base64 של מפתח SSH פרטי (ed25519) שיש לו גישת write ל-`/var/www/outlook-addin/` ב-platform.dev | ייצור: `ssh-keygen -t ed25519`, אחר כך `[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\.ssh\id_ed25519"))` | +| `MATTERMOST_WEBHOOK_RELEASES` | URL של webhook לערוץ `#git-verelasim` | מ-Mattermost → Integrations → Incoming Webhooks | + +### 3.4 — הגדרת Gitea Actions Secrets + +ב-Gitea: כנס לרפו `espocrm-extensions/OutlookAddin` → **Settings → Actions → Secrets**. + +צור secret עבור כל אחד מהמפתחות שלמעלה (אותם שמות בדיוק): + +- `CODESIGN_THUMBPRINT` +- `PLATFORM_DEV_SSH_KEY` +- `MATTERMOST_WEBHOOK_RELEASES` + +(שני האחרים, `CODESIGN_PFX_BASE64` ו-`CODESIGN_PASSWORD`, לא נדרשים ב-CI כל עוד ה-PFX כבר מותקן ב-`Cert:\CurrentUser\My` של ה-Build Runner). + +### 3.5 — הגדרת nginx ב-platform.dev + +**מטרה:** השרת שעורכי הדין יורידו ממנו את ההתקנה והעדכונים. + +התחבר ל-`platform.dev.marcus-law.co.il` כ-root: + +```bash +# צור תיקייה +sudo mkdir -p /var/www/outlook-addin +sudo chown -R www-data:www-data /var/www/outlook-addin + +# הוסף את משתמש ה-SSH של ה-CI לקובץ authorized_keys +sudo mkdir -p /root/.ssh +echo "ssh-ed25519 AAAA… klear-ci@build-runner" >> /root/.ssh/authorized_keys +sudo chmod 600 /root/.ssh/authorized_keys +``` + +צור קובץ `/etc/nginx/sites-available/outlook-addin.conf`: + +```nginx +server { + listen 443 ssl http2; + server_name platform.dev.marcus-law.co.il; + + ssl_certificate /etc/letsencrypt/live/platform.dev.marcus-law.co.il/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/platform.dev.marcus-law.co.il/privkey.pem; + + location /outlook-addin/ { + alias /var/www/outlook-addin/; + autoindex off; + + # MIME types שדרושים ל-ClickOnce + types { + application/x-ms-application application; + application/x-ms-manifest manifest; + application/octet-stream vsto; + application/octet-stream deploy; + } + + # לא לכאש — חייבים לקבל את הגרסה הכי חדשה + add_header Cache-Control "no-cache, must-revalidate"; + } +} +``` + +הפעל: + +```bash +sudo ln -s /etc/nginx/sites-available/outlook-addin.conf /etc/nginx/sites-enabled/ +sudo nginx -t # ודא שאין שגיאה תחבירית +sudo systemctl reload nginx +``` + +בדוק שהשרת עונה (גם אם אין עוד תוכן): +```bash +curl -I https://platform.dev.marcus-law.co.il/outlook-addin/ +# צריך לקבל 403 או 404 — לא 502 או SSL error +``` + +### 3.6 — הפצת תעודת חתימה ל-10 מחשבי עורכי הדין דרך GPO + +**מטרה:** כל מחשב לקוח חייב לסמוך על תעודת Marcus-Law Klear, אחרת ClickOnce ידחה את ההתקנה עם אזהרת "Unknown Publisher". + +1. העתק את `codesign.cer` משלב 3.2 לתיקיית SYSVOL: + ``` + \\marcus-law.local\SYSVOL\marcus-law.local\Scripts\certs\codesign.cer + ``` + +2. פתח **Group Policy Management Console** (`gpmc.msc`) על שרת Active Directory. + +3. צור או ערוך GPO בשם **"Klear Code-Signing Certificate"** ושייך אותו ל-OU של עורכי הדין (לדוגמה `OU=Attorneys,DC=marcus-law,DC=local`). + +4. ב-GPO Editor, נווט אל: + `Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies` + +5. **קליק ימני** על **Trusted Publishers → Import…** → בחר את `codesign.cer`. + +6. חזור על אותה פעולה תחת **Trusted Root Certification Authorities** (כי זו תעודה self-signed שלא חתומה ע"י CA אמיתי). + +7. דחוף את ה-GPO לכל המכונות: + ```powershell + # מ-Domain Controller + Invoke-Command -ComputerName (Get-ADComputer -Filter * -SearchBase "OU=Attorneys,DC=marcus-law,DC=local").Name -ScriptBlock { gpupdate /force } + ``` + +8. **ודא** במחשב אחד של עורך-דין: + ```powershell + certutil -store -user TrustedPublisher | findstr /C:"Marcus-Law Klear" + ``` + אם רואים `CN=Marcus-Law Klear` — מוכן. אם לא — ה-GPO לא הגיע, נסה `gpupdate /force` שוב. + +--- + +## 4. שחרור גרסה ראשונה (`v1.0.0`) + +לאחר שכל ההקמה הסתיימה, השחרור הראשון: + +```bash +# במכונה של המפתח, אחרי שכל הקוד ב-main: +git tag v1.0.0 +git push origin v1.0.0 +``` + +מה קורה ברקע: + +1. Gitea Actions מתחיל job בשם `publish` על runner `windows`. +2. הוא בונה ב-Release, חותם, מריץ mage עם גרסה `1.0.0.0`. +3. מעלה ל-`platform.dev:/var/www/outlook-addin/`. +4. שולח הודעה ל-Mattermost בערוץ `#git-verelasim`: + > 📦 OutlookAddin **v1.0.0** משוחרר — https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto + +**מעקב:** ראה את ה-job ב-`https://gitea.dev.marcus-law.co.il/espocrm-extensions/OutlookAddin/actions`. אמור להסתיים תוך 2-3 דקות. אם נכשל — קליק על השלב הכושל ובדוק את הלוג. + +**בדיקת קצה:** + +1. ב-Edge / Chrome פתח `https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto` — אמור להראות XML. +2. במחשב נקי של עורך-דין (או VM לבדיקות): + - הורד את `setup.exe` או פתח את `OutlookAddin.vsto` ישירות. + - אמור להופיע דיאלוג ClickOnce **בלי אזהרת "Unknown Publisher"** (כי ה-GPO הפיץ את התעודה). + - אשר התקנה → תוסף נטען ב-Outlook → רואים את כפתור "Klear" בריבון. + +--- + +## 5. שחרור עדכון חדש (יום-יום) + +לאחר שינויי קוד, החזרה לפעולה: + +```bash +# 1. ודא שכל השינויים ב-main +git status # אמור להיות clean +git pull --rebase + +# 2. בחר מספר גרסה לפי semver +# - תיקון באג → v1.0.X (PATCH) +# - פיצ'ר חדש קטן → v1.X.0 (MINOR) +# - שינוי שובר תאימות לאחור → vX.0.0 (MAJOR) +git tag v1.0.1 +git push origin v1.0.1 +``` + +ה-CI ירוץ אוטומטית כמו בשחרור הראשון. + +**אצל הלקוחות:** +- ClickOnce בודק עדכון אוטומטית **כל 7 ימים** (הגדרה ב-csproj: `UpdateInterval=7`). +- כדי **להאיץ** עדכון אצל לקוח מסויים: + 1. סגור את Outlook לגמרי. + 2. פתח את Outlook שוב. + 3. אם עברו לפחות 7 ימים מבדיקת ה-update הקודמת — יבדוק עכשיו ויעדכן. + 4. אם לא — אפשר לנקות את ה-ClickOnce cache: + ```powershell + rundll32.exe dfshim.dll,CleanOnlineAppCache + ``` + ואז לפתוח שוב את `https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto`. + +--- + +## 6. ניטור ופתרון תקלות + +### Mattermost notifications +- `#git-verelasim` — מקבל הודעת הצלחה/כישלון לכל release. +- אם כישלון — הקישור בהודעה לוקח ישר ל-Gitea Actions log. + +### לוגי הקלינט +אם לקוח מתלונן שהעדכון לא הגיע: +``` +%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-YYYYMMDD.log +``` +שורת `AddInHost starting up` מופיעה בכל פתיחת Outlook עם הגרסה הנוכחית. + +### בדיקה שהגרסה החדשה אכן בשרת +```bash +curl -s https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto | grep -E "(version|application)" +``` +אמור להציג את הגרסה החדשה. + +### Rollback מהיר +אם גרסה שוחררה ויש בה באג קריטי: + +```bash +# על platform.dev (כ-root) +cd /var/www/outlook-addin + +# העבר את הגרסה הבעייתית הצידה +sudo mv "Application Files/OutlookAddin_1_0_1_0" "_quarantine_1_0_1_0" + +# החזר את ה-.vsto לגרסה הקודמת +# (קל יותר: דחוף תיוג חדש v1.0.2 שמחזיר את הקוד הקודם) +git revert +git tag v1.0.2 +git push origin main v1.0.2 +``` + +ה-CI יבנה אוטומטית את `v1.0.2` ותוך 7 ימים כל הלקוחות יחזרו אחורה. + +### כשלים נפוצים + +| שגיאה | סיבה | פתרון | +|---|---|---| +| `signtool: Failed (0x80092004)` | התעודה לא ב-`Cert:\CurrentUser\My` ב-Build Runner | התקן את ה-PFX שוב במכונה | +| `mage: not recognized` | חסר .NET Framework 4.8 Developer Pack | התקן מ-winget לפי שלב 3.1 | +| `Permission denied (publickey)` ב-rsync | SSH key לא נכנס ל-authorized_keys על platform.dev | חזור על שלב 3.5 והוסף את הציבורי | +| לקוח מקבל "Unknown Publisher" | GPO לא הפיץ את התעודה למחשב הזה | `gpupdate /force` במחשב הלקוח | +| לקוח לא מקבל עדכון אחרי 7 ימים | ה-ClickOnce cache תקוע | `rundll32 dfshim.dll,CleanOnlineAppCache` ופתח שוב | + +--- + +## 7. בדיקה אם ההקמה הצליחה + +עברו את הצ'קליסט הזה אחרי הקמה ראשונית: + +- [ ] CI runner מופיע online ב-Gitea Admin +- [ ] שלושת ה-secrets קיימים ב-Gitea Actions Settings +- [ ] `curl https://platform.dev.marcus-law.co.il/outlook-addin/` חוזר 200/403 (לא 502 / connection refused) +- [ ] `certutil -store -user TrustedPublisher` במחשב לקוח מציג `Marcus-Law Klear` +- [ ] Mattermost incoming webhook עובד — בדוק עם `curl -X POST -d '{"text":"test"}' ` +- [ ] `git tag v0.0.1-test && git push origin v0.0.1-test` מפעיל את ה-CI workflow +- [ ] ה-job מסתיים בירוק תוך 5 דקות +- [ ] מחיקת הטאג הניסיוני אחרי: `git push --delete origin v0.0.1-test && git tag -d v0.0.1-test` + +--- + +## 8. תחזוקה תקופתית + +| משימה | תדירות | +|---|---| +| חידוש תעודת חתימה (אחרי 3 שנים) | פעם ב-3 שנים — לפני התפוגה תעודה חדשה צריכה GPO חדש | +| חידוש Let's Encrypt לתעודה של platform.dev | אוטומטי, אבל לבדוק שה-cron פועל | +| עדכון VS Build Tools / Windows SDK ב-runner | כל 6 חודשים | +| ניקוי גרסאות ישנות מ-`/var/www/outlook-addin/Application Files/` | לאחר שכל הלקוחות עברו (אופציונלי, חוסך מקום) | + +--- + +## 9. מסמכים קשורים + +- `docs/PROJECT-BRIEFING.md` — סקירת הפרויקט (תכנון מקורי) +- `docs/ARCHITECTURE.md` — ארכיטקטורת התוסף (לא ה-CI) +- `docs/IT-SETUP.md` — מדריך IT באנגלית (כולל פירוט API keys ב-EspoCRM) +- `docs/ONBOARDING.md` — מדריך לעורך-הדין (לקצה — לא לכם) +- `.gitea/workflows/build.yml` — הגדרת CI עצמה (הקובץ שמריץ את הכל) +- `tools/install-protocol.ps1` — סקריפט לרישום `outlookaddin://` במחשבי הלקוח (אופציונלי) + +--- + +## 10. קשר ועזרה + +- בעיות עם הקוד עצמו: **chaim@marcus-law.co.il** +- בעיות CI / nginx / GPO: צוות תשתיות פנימי +- חירום (כל הלקוחות תקועים): roll-back מיידי לפי סעיף 6, ואז דחיפת תיקון