OutlookAddin/docs/AUTO-UPDATE-SETUP.md

מערכת עדכון אוטומטי — מדריך הקמה לצוות תשתיות

מסמך זה מסביר מה צריך להקים פעם אחת כדי שתוסף 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. התקן את הכלים הבאים (כולם בחינם):

   # 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 שלכם:

   .\act_runner.exe register `
     --no-interactive `
     --instance https://gitea.dev.marcus-law.co.il `
     --token <token-from-gitea-admin> `
     --name "winbuild-01" `
     --labels "windows"
   

6. התקן את ה-runner כשירות Windows כדי שירוץ ברקע:

   .\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):

# יצירת תעודה לתקופה של 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 "<password-חזק>" -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:

# צור תיקייה
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:

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";
    }
}

הפעל:

sudo ln -s /etc/nginx/sites-available/outlook-addin.conf /etc/nginx/sites-enabled/
sudo nginx -t       # ודא שאין שגיאה תחבירית
sudo systemctl reload nginx

בדוק שהשרת עונה (גם אם אין עוד תוכן):

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 לכל המכונות:

   # מ-Domain Controller
   Invoke-Command -ComputerName (Get-ADComputer -Filter * -SearchBase "OU=Attorneys,DC=marcus-law,DC=local").Name -ScriptBlock { gpupdate /force }
   

8. ודא במחשב אחד של עורך-דין:

   certutil -store -user TrustedPublisher | findstr /C:"Marcus-Law Klear"
   

   אם רואים CN=Marcus-Law Klear — מוכן. אם לא — ה-GPO לא הגיע, נסה gpupdate /force שוב.

---

4. שחרור גרסה ראשונה (v1.0.0)

לאחר שכל ההקמה הסתיימה, השחרור הראשון:

# במכונה של המפתח, אחרי שכל הקוד ב-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. שחרור עדכון חדש (יום-יום)

לאחר שינויי קוד, החזרה לפעולה:

# 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 ירוץ אוטומטית כמו בשחרור הראשון.

אצל הלקוחות:

• ה־VSTO runtime בודק את ה-.vsto manifest בכל פתיחה של Outlook (משוחזר מ-<UpdatePeriodically>false</UpdatePeriodically> ב-csproj החל מ-v1.2.9; קודם זה היה פעם ב-7 ימים). הבדיקה היא GET של ~6KB, ~100ms — בלתי מורגש בזמן הטעינה.
• ה-CI מציב /p:MinimumRequiredVersion=<tag> בכל build, אז מיד כשהבדיקה מזהה גרסה חדשה — ההתקנה נכפית בלי דיאלוג.
• תרגום מעשי: 30 שניות אחרי git push --tags ה-CI מסיים → תוך 2-3 דקות החבילה נדחפת ל-CDN → בכניסה הבאה של כל אחד מהלקוחות ל-Outlook הוא רץ על הגרסה החדשה. בלי שום פעולה ידנית מצידם.
• הכפתור "בדוק עדכונים" בהגדרות רק מודיע ("זמינה גרסה X — סגור ופתח Outlook"). הוא לא יכול להתקין מתוך תהליך Outlook רץ — VSTOInstaller.exe לא יכול לדרוס DLLs נעולים, וה-ApplicationDeployment API נכשל ב-TrustNotGrantedException בהקשר VSTO. ההתקנה תמיד קורית רק דרך ה-runtime בעלייה של Outlook. [פירוט בזיכרון: feedback_vsto_updater_api.md]
• תקלה נדירה — לקוח שהותקן ידנית עם dev cert (HP-OFFICE1\<user>, publicKeyToken 41d8d795775ea8cb) לא יכול לעבור auto-update לגרסת prod cert (Marcus-Law OutlookAddin, publicKeyToken c68d2b4c25051c5b) — ClickOnce מתייחס אליהן כשתי אפליקציות שונות. פעם אחת: Apps & Features → uninstall של MarcusLaw.OutlookAddin → התקנה חדשה מ-https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto. אחרי זה auto-update עובד.

---

6. ניטור ופתרון תקלות

Mattermost notifications

• #git-verelasim — מקבל הודעת הצלחה/כישלון לכל release.
• אם כישלון — הקישור בהודעה לוקח ישר ל-Gitea Actions log.

לוגי הקלינט

אם לקוח מתלונן שהעדכון לא הגיע:

%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-YYYYMMDD.log

שורת AddInHost starting up מופיעה בכל פתיחת Outlook עם הגרסה הנוכחית.

בדיקה שהגרסה החדשה אכן בשרת

curl -s https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto | grep -E "(version|application)"

אמור להציג את הגרסה החדשה.

Rollback מהיר

אם גרסה שוחררה ויש בה באג קריטי:

# על 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 <commit-של-הבאג>
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"}' <webhook-url>
• 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, ואז דחיפת תיקון