אירוח עצמי ורישוי

Institflow נמכרת באירוח עצמי בלבד — בסיס קוד אחד, חוזה ממשק אחד, הפועלים כולם על תשתית שאתם שולטים בה.

פריסה#

חבילת Docker חד-דיירית (api, worker, web, caddy, ולצידם Postgres/Redis/Garage) שאתם מריצים על שרת משלכם, מוגבלת ברישיון חתום שמונפק מפלטפורמת הספק שלכם. אין חלופה רב-דיירית שמאוחסנת אצל הספק לבחור בה במקום זאת.

התקנת גרסת האירוח העצמי#

דרישות מוקדמות: שרת חדש עם Ubuntu 22.04, Ubuntu 24.04, Ubuntu 26.04 או Debian 12, כאשר הפורטים 80/443 פנויים ונגישים, וטוקן התקנה (install token) מהקונסולה של הספק שלכם (Customer ← Install ← Generate install command — מוצג פעם אחת).

פקודה אחת#

curl -fsSLo institflow-install.sh https://license.institflow.com/api/v1/install/script
sudo bash institflow-install.sh

הסקריפט מבקש מכם את טוקן ההתקנה (קלט מוסתר, כך שהוא לעולם לא מגיע להיסטוריית המעטפת שלכם — קיים גם --token לאוטומציה, שבכוונה אינו מופיע בפקודה שלמעלה), ואז: מתקין את Docker ממאגר ה-apt הרשמי שלו אם הוא חסר, תובע (claim) את הטוקן שלכם מול מישור הבקרה, יוצר כל סוד נוסף על השרת הזה עצמו (שום דבר סודי לעולם לא עובר מהספק אליכם מלבד הרישיון ופרטי גישה למרשם, בדיוק כמו קודם), כותב את docker-compose.yml/.env/Caddyfile, מפעיל את החבילה, ממתין עד שכל שירות בריא (healthy) ועד שהכתובת שלכם נפתרת, ואז מדפיס את כתובת ההגדרה שלכם, SETUP_TOKEN חד-פעמי ומפתח גיבוי פרטי חד-פעמי. הוא מסרב לרוץ בכל הרשאה שאינה root, ובכל מערכת הפעלה מלבד ארבע אלה, ולעולם אינו מזרים את הרשת ישירות למעטפת — אתם מורידים את הסקריפט קודם ואז מריצים אותו, כך שאפשר לקרוא אותו לפני כן.

השרת שלכם מקבל אוטומטית כתובת משלו תחת הדומיין institflow.app של הספק (<slug-המכון-שלכם>.institflow.app, עם רשומת DNS ותעודה מנוהלות עבורכם). העבירו --domain your-own-domain.org במקום זאת כדי להשתמש בדומיין שכבר בבעלותכם — הפנו את רשומת ה-DNS (A/AAAA) שלו לשרת הזה קודם; המתקין בודק זאת ומסרב אם לא.

הרצה חוזרת של הסקריפט על שרת שכבר יש בו /opt/institflow/.env תיסרב אלא אם תוסיפו --reinstall, שלעולם אינה נוגעת בוליומי הנתונים שלכם ושומרת כל ערך שכבר קיים ב-.env.

עדכונים מגיעים מעצמם לאחר מכן — ראו "עדכון" למטה; אין צורך להריץ דבר נוסף ידנית.

התחברות ראשונה#

פתחו את כתובת ההגדרה שהמתקין הדפיס, הדביקו את ה-SETUP_TOKEN, וצרו משם את המכון שלכם ואת חשבון הבעלים שלכם. אותו עמוד מפסיק להתקיים לאחר מכן: אי אפשר להשתמש שוב בטוקן כדי ליצור מכון שני.

התקנה ידנית (נספח)#

הפקודה האחת שלמעלה היא הדרך הנתמכת. אם מודל האיומים שלכם דורש לבצע כל שלב ידנית במקום זאת — בלי להוריד סקריפט ולהריץ אותו כ-root — הנה אותה התקנה, שלב אחר שלב:

1. השיגו רישיון. הספק שלכם יוצר את הדייר שלכם בפלטפורמה שלו ומנפיק לו רישיון — אתם מקבלים LICENSE_KEY, שמוצג פעם אחת. אין מפתח אימות שצריך למלא: המפתח שהמופע שלכם בודק מולו את הרישיון מוטבע בתוך התמונות שפורסמו, ולכן אף אחד — כולל אתם — לא יכול להחליף אותו.

2. מלאו את משתני הסביבה. העתיקו את docker/self-hosted.env.example אל docker/.env ומלאו כל ערך — סודות נוצרים עם openssl rand -base64 32, וזוג מפתחות ה-JWT באמצעות סקריפט keys:generate חד-פעמי.

3. הפעילו את החבילה.

   bash

   docker compose -f docker/compose.self-hosted.yml --env-file docker/.env up -d
   docker compose -f docker/compose.self-hosted.yml --env-file docker/.env ps

   api-init הוא מריץ מיגרציות חד-פעמי, ומצופה שיסתיים בקוד 0; כל שאר השירותים נשארים רצים.

4. התחברות ראשונה — אותו עמוד הגדרה שלמעלה.

עדכון הוא העלאת גרסה בתוספת docker compose pull && up -d — api-init רץ מחדש (באופן אידמפוטנטי) בכל הפעלה וחוסם את הממשק מלשרת תנועה עד שהמיגרציות מסתיימות.

גודל השרת#

ה-API מודד את המעבד והזיכרון שהוא באמת יכול להשתמש בהם — המגבלה של הקונטיינר עצמו, לא כל החומרה של המארח — ומשווה זאת למה שמספרי התלמידים והצוות הפעילים במכון שלכם דורשים. זו אזהרה בלבד, לעולם לא חסימה: ההתקנה, ההפעלה וכל תכונה ממשיכים לעבוד ללא קשר לגודל השרת שמתחתיהם. כשהשרת שלכם מתחת לגודל המומלץ, מופיע באנר בעמוד הגדרות ← רישיון באפליקציה עבור הבעלים/מנהל, ו-api-init מדפיס את אותה בדיקה ליומן שלו בכל הפעלה.

כל שורה למטה נמדדה בפועל, לא הוערכה: מסלול הכתיבה (סימון נוכחות של שיעור ורישום קבוצת תשלומים — שתי הפעולות שדלפק קבלה עמוס באמת מתחרה עליהן) הורץ מול שרת לקוח מדומה שנבנה מהתמונות של הפרויקט הזה עצמו, במספרים גדלים של אנשי צוות שכותבים באותו רגע, עד שזמן התגובה p95 של כל גודל נשאר מתחת ל-800 מילישניות (docs/reports/sizing-2026-09-22.md, פריט K-32).

אחסון קבצים (Object storage)#

קבצים שהועלו (מסמכי תלמידים וצוות, חשבוניות, חומרי קורסים) נשמרים ב-Garage — קובץ בינארי סטטי יחיד שרץ כשירות משלו, לעולם לא כהתקנה ברמת המארח. הוא אינו חושף שום פורט על המארח: האפליקציה מגיעה אליו רק דרך רשת ה-compose (ה-API של S3 שלו על פורט 3900, API ניהול על פורט 3903, שניהם פנימיים בלבד), ושירות חד-פעמי בשם object-store-init יוצר את חבילת האחסון (bucket) שלו ומפתח אפליקציה מתוחם בכל הפעלה, באופן אידמפוטנטי — אין דבר להריץ ידנית. אותו מפתח יכול לקרוא ולכתוב רק בתוך חבילת האחסון הזו ולא מעבר לכך: הוא לא יכול ליצור, לרשום או למחוק חבילת אחסון.

הדפדפן שלכם מעלה ומוריד קבצים דרך הדומיין שלכם עצמכם, לעולם לא דרך שרת אחסון נפרד: https://<הדומיין-שלכם>/institflow-objects/…‎, מנותב על ידי Caddy ומוגבל שם לתקרה של 20 מגה-בייט. ה-API חותם כל קישור עבור אותה כתובת בדיוק.

התקנה חדשה יוצרת ארבעה סודות בקובץ ה-.env — GARAGE_RPC_SECRET, GARAGE_ADMIN_TOKEN, OBJECT_STORE_ACCESS_KEY_ID, OBJECT_STORE_SECRET_ACCESS_KEY — וכותבת ערכי מילוי (placeholders) ריקים ל-S3_BUCKET/S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY, שרק ההעברה החד-פעמית שלמטה אי פעם קוראת אותם. כדי להשתמש בספק תואם-S3 משלכם במקום ה-Garage המצורף, הגדירו את OBJECT_STORE_ENDPOINT, OBJECT_STORE_PUBLIC_ENDPOINT, OBJECT_STORE_BUCKET ו-OBJECT_STORE_REGION. גרסה זו דורשת Docker Compose 2.23.1 ומעלה — המתקין בודק זאת לפני שהוא עושה כל דבר אחר.

שדרוג מגרסה 1.5.x#

התקנות על 1.5.x שמרו את הקבצים שלהן ב-MinIO מצורף. העבירו אותם ל-Garage עם:

curl -fsSLo institflow-install.sh https://license.institflow.com/api/v1/install/script
sudo bash institflow-install.sh --reinstall --adopt

זו אותה פקודה חד-פעמית שמעבירה התקנה אל המעדכן המתקן את עצמו (ראו עדכונים ותיקונים אוטומטיים למטה; --refresh-bundle הוא שמה הישן ועדיין עובד). בהתקנת 1.5.x היא גם מוסיפה את ארבעת הסודות שלמעלה ל-.env בלי לשנות שום ערך שכבר קיים, ומפעילה את ההעתקה החד-פעמית: api-init מעתיק כל קובץ שהועלה מ-MinIO אל Garage ומאמת כל אחד — גודל, סכום ביקורת (checksum), והשורה התואמת במסד הנתונים — לפני שה-API וה-worker רשאים לעלות. ה-MinIO הישן שלכם נשאר שלם וסמכותי עד שההעתקה מאומתת במלואה, וממשיך לרוץ כשירות minio-legacy כך שעדיין אפשר להעתיק אליו את הקבצים בחזרה אם תצטרכו אי פעם לחזור לגרסה קודמת.

פעולה זו מסרבת לבצע שום שינוי אם תמונת MinIO כבר לא נמצאת על השרת שלכם (המקור הפסיק לפרסם אותה) — שחזרו אותה מגיבוי של /var/lib/docker, או העתיקו אותה משרת אחר עם docker save … | docker load, ואז הריצו מחדש. עד שתריצו אותה, התקנת 1.6.0 על החבילה הישנה ממשיכה לעבוד על MinIO בדיוק כמו קודם, והבעלים רואה התראת "נדרש שדרוג אחסון" בהגדרות ← רישיון ← עדכונים אוטומטיים.

חזרה אחורה לאחר שדרוג#

אם אתם צריכים לחזור לגרסה שלפני 1.6.0 אחרי שהמשתמשים שלכם כבר העלו קבצים חדשים ל-Garage, העתיקו אותם אחורה קודם:

cd /opt/institflow
sudo docker compose run --rm api-init node dist/scripts/storage-migrate.js --reverse

פעולה זו מעתיקה כל אובייקט מ-Garage בחזרה אל MinIO ומאמתת אותו באותו אופן שבו השדרוג עשה זאת, בלי לשנות את מסד הנתונים שלכם. רק אז החזירו את docker-compose.yml ואת Caddyfile מ-state/snapshots/*/‎ וחיזרו אחורה. השאירו את קובץ ה-.env הנוכחי כפי שהוא: מה שהשדרוג הוסיף לו נשמט על ידי החבילה הישנה, וסודות האחסון החדשים חייבים להישאר כפי שהם לשדרוג מאוחר יותר.

עדכונים ותיקונים אוטומטיים#

החל מ-1.7.0 רץ בכל התקנה שומר קטן על השרת עצמו — סקריפט שטיימר של systemd (institflow-guardian.timer) מפעיל כל שתי דקות — והמעדכן, קונטיינר שהשומר מריץ עם docker run. השומר מוודא שהמעדכן קיים, רץ, והוא בדיוק התמונה שהספק חתם עבור הגרסה שלכם, ומחזיר אותו אם לא; המעדכן מחזיר את השומר אם הוא נפגע.

כל גרסה נושאת תיאור חתום של התקנה תקינה של אותה גרסה: אילו קבצים, באיזה תוכן והרשאות, אילו שירותים, אילו מפתחות ב-.env. המעדכן מתקן רק מה ששונה ממנו, ורק מתוך רשימה קבועה של פעולות בטוחות — כתיבה חוזרת של קובץ ספק חסר, החזרת הרשאה, הפעלת שירות שנעצר, הוספת מפתח חסר ב-.env שאפשר ליצור בבטחה, הסרת קונטיינר ה-updater הישן. הוא לעולם אינו מוחק נתונים, וליום, מסד נתונים או גיבוי; אינו משנה ערך שכתבתם ב-.env (רק מוסיף מפתחות חסרים); אינו יוצר סיסמה או מפתח שאובדנם היה נועל את הנתונים שלכם (הוא מדווח עליהם במקום זאת); אינו נוגע ברישיון; ואינו כותב מעל קובץ שאינו יכול להוכיח שהספק כתב. קובץ ששיניתם ביד מדווח ואינו מתוקן — אם תרצו את גרסת הספק בחזרה, הריצו sudo institflow-guardian accept-vendor-files (העותק שלכם נשמר תחת state/quarantine/). שימו את הגדרות ה-Caddy שלכם ב-caddy/custom.d/ ואת שינויי ה-compose שלכם ב-docker-compose.override.yml; שניהם שלכם ואינם נשפטים.

לפני כל תיקון או עדכון המעדכן לוקח גיבוי מלא — מסד הנתונים, הקבצים שלכם והגדרות השרת עצמו — ובודק אותו; בלי גיבוי מאומת הוא לא משנה דבר. עדכון מפעיל את המעדכן של הגרסה הבאה בעוד שהנוכחי נשאר אחראי: אם הגרסה החדשה לא עולה תקינה, הקודמת מופעלת שוב, והשרת ממשיך לשרת. מסד הנתונים לעולם אינו משוחזר אוטומטית.

פקודות שימושיות, כ-root: institflow-guardian status (מה רץ, הגרסה המוצמדת, עדכון בתהליך), institflow-guardian plan (מה המעדכן היה מתקן עכשיו), institflow-guardian maintenance on|off (כשהוא פעיל שום דבר לא מופעל, נוצר מחדש או מתעדכן; הגיבויים ממשיכים), institflow-guardian check (בדיקת נזק וגרסה חדשה תוך דקה). הבעלים יכול להעביר את התיקונים האוטומטיים לדיווח בלבד בהגדרות ← רישיון ← עדכונים אוטומטיים.

העברת התקנה שנעשתה לפני 1.7.0#

התקנה שנעשתה לפני 1.7.0 מריצה את המעדכן הישן, שאינו יכול להחליף את עצמו ולא להתקין את השומר. הריצו את זה פעם אחת, כ-root, על השרת — שום דבר נוסף לא יידרש לעולם אחר כך:

curl -fsSLo institflow-install.sh https://license.institflow.com/api/v1/install/script
sudo bash institflow-install.sh --reinstall --adopt

היא מאמתת את הגרסה החתומה החדשה ביותר לפני שהיא משנה דבר, לוקחת גיבוי מלא, מתקינה את השומר, מסירה את קונטיינר ה-updater הישן (וליום הנתונים שלו נשמר), ומעבירה את השליטה למעדכן החדש, שמעביר את ההתקנה תחת גיבוי שני ומאומת ומחזיר הכול כפי שהיה אם משהו נכשל. התקנה שסודרה ידנית ב-/opt/institflow/docker מועברת קודם אל /opt/institflow, אחרי גיבוי משלה; כל סידור אחר נדחה עם פירוט מה נמצא. עד שהיא מורצת, ההתקנה ממשיכה לעבוד על הגרסה הנוכחית שלה.

עם מי ההתקנה שלכם מדברת#

בדיוק שלושה שרתים חיצוניים, ולא יותר — אף אחד מהם אינו פרוקסי לתעבורת המבקרים שלכם, ושום דבר לא מנתב בקשות של משתמשי קצה דרכנו:

1. שרת הרישיונות (license.institflow.com) — פעימת לב שעתית, ומניפסט העדכון החתום שהמעדכן שלכם סוקר. חוסר נגישות אליו לא משנה דבר מיוזמתו; ראו מחזור חיי הרישיון למטה.
2. ממסר ההודעות (relay) — אותו שרת כמו שרת הרישיונות, לא כתובת נפרדת. בהפעלה יוצרת ההתקנה שלכם זוג מפתחות משלה ונרשמת באמצעות LICENSE_KEY; מאותו רגע היא יכולה לבקש מהממסר לשלוח את הדואר המערכתי שלכם (איפוס סיסמה, הזמנות צוות/פורטל — חינם תמיד, לעולם לא נחסם על ידי יתרה) וכן, אם תבחרו בכך, את הדואר המשולם של המכון עצמו (הגדרות ← התראות ← ספקים). אין מה להגדיר כאן — אין משתנה סביבה ייעודי לממסר. השרת הראשון של הרישיון שלכם מאושר מיד; התקנה מחדש על שרת אחר ממתינה לאישור של Institflow, וכך גם שרת שהותקן לראשונה במתקין בגרסה שקודמת לגרסה 1.6.4 לאחר שהוא נרשם מחדש — הגדרות ← התראות ← ספקים מציג את המצב הזה, והדואר חוזר מעצמו ברגע שהוא מאושר.
3. מרשם התמונות של הספק (registry.institflow.com) — למשיכה בלבד, מגיעים אליו רק דרך docker login/docker compose pull בהתקנה ראשונה או בעדכון, לעולם לא על ידי המערכת בזמן ריצה.

SMTP_URL בקובץ ה-.env שלכם נדרש כדי שה-API יעלה, אך החל מגרסה זו שום דבר לא נשלח דרכו בפועל — כל דואר מערכתי וכל הודעת דואר של המכון עוברים דרך הממסר שלמעלה, אלא אם תוסיפו בכוונה פרטי גישה משלכם ל-SMTP בתוך האפליקציה עצמה (הגדרות ← התראות ← ספקים) — וזהו שרת הדואר החיצוני היחיד שאתם בוחרים בעצמכם.

מחזור חיי הרישיון#

רישיונות נקבעים ידנית על ידי הספק שלכם — אין חיוב אוטומטי. כשתקופת התשלום מסתיימת, המערכת רק מזהירה; היא לעולם לא חוסמת גישה מיוזמתה.

1. בתוקף — תפקוד מלא, שום דבר לא נראה למשתמשי הקצה.
2. פג תוקף — עדיין מתפקד במלואו, ללא הגבלת זמן. כל תשובה נושאת כותרת X-Subscription-Warning: expired; since=<date>, ואפליקציית הווב מציגה באנר לבעלים ולמנהלים בלבד עם התאריך. שום דבר נוסף לא משתנה — מכון שפג תוקפו שומר על גישה מלאה עד שמישהו נועל אותו.
3. נעול — המצב היחיד שחוסם גישה, והוא תמיד תוצאה של פקודת נעילה מפורשת ונושאת סיבה מהספק שלכם — פקיעת תוקף לבדה לעולם לא מייצרת אותו. בקשות שתחומות לדייר מקבלות 402 SUBSCRIPTION_SUSPENDED, למעט אימות, בדיקות תקינות ועמוד החיוב עצמו. נתונים לעולם אינם נמחקים או משתנים — שחרור הנעילה מחזיר גישה מלאה מיד, בדיוק במקום שבו עצרתם.

מדיניות נעילה אוטומטית ברמת הפלטפורמה יכולה לנעול דייר שפג תוקפו אוטומטית לאחר השהיה שניתנת להגדרה — כבויה כברירת מחדל, כך ששום דבר לא נעול אלא אם מישהו הפעיל אותה. עקיפה ברמת דייר בודד יכולה גם להכניס או להוציא מכון יחיד מהמדיניות הזו, בלי קשר לברירת המחדל של הפלטפורמה.

התקנה באירוח עצמי ממשיכה לעבוד ללא הגבלת זמן כשאין לה גישה לשרת הרישיונות — ניתוק מהרשת לבדו לא משנה דבר, גם אם כשלו רצף בדיקות שלם. התקנה מדווחת לספק שלכם על סימני שיבוש (שעון שהוחזר לאחור, פעימת לב חסרה וכדומה), אבל אלה סימני התראה בלבד: שום דבר לא נעול אוטומטית בגלל סימן שנדלק, אלא רק דרך אותה פקודה חתומה ומפורשת שאדם מנפיק. אם התקנה נעולה ושרת הרישיונות אינו זמין, הספק יכול להנפיק טוקן שחרור חד-פעמי שתדביקו במסך הניהול של האירוח העצמי כדי להחזיר גישה במצב לא מקוון.

הערות אבטחה#

• החליפו כל סוד בקובץ הסביבה לדוגמה לפני עלייה לאוויר — אף אחד מהערכים הריקים שבו אינו ברירת מחדל בטוחה.
• TLS מוגדר אוטומטית (Caddy) כל עוד הדומיין שלכם נפתר ופורט 80 נגיש עבור אתגר ה-ACME הראשוני.
• רק 80/443 צריכים להיות נגישים מהאינטרנט — Postgres/Redis/Garage והממשק עצמו לעולם אינם נחשפים למארח.
• MASTER_KEY מצפין את פרטי הגישה לספקים שהדייר מספק (מפתחות API של WhatsApp/SMS/אימייל) במנוחה — התייחסו אליו כאל סיסמת מסד נתונים, וגבו אותו. אובדנו הופך כל אישור גישה שנשמר לבלתי ניתן לפענוח לצמיתות.

שטח דיסק ומד האחסון#

דף ההגדרות ← אחסון מציג כמה מקום הקבצים של המוסד שלכם תופסים וכמה נשאר בדיסק השרת. הקבצים שמועלים (קבצי שיעורים וכל העלאה אחרת) נשמרים בשירות garage המצורף, על הדיסק של השרת עצמו.

השרת שומר מקום פנוי עבור מסד הנתונים, הגיבויים והעדכונים: הגדול מבין 10% מהדיסק ו-5 GiB. העלאות נדחות בהודעה ברורה לפני שהן ינצלו את המקום השמור, ומאגר האובייקטים עצמו מחזיק מכסה קשיחה באותו גבול, כך שגם העלאה ישירה לא יכולה למלא את הדיסק. המד הופך לצהוב ב-80% ולאדום ב-95% ממה שעוד אפשר לאחסן, והדף מציג באנר מ-80%. אם ההתקנה שלכם משתמשת בספק S3 חיצוני במקום במאגר המצורף, המד מציג רק את השטח בשימוש וההעלאות אינן מוגבלות.

כדי להוסיף מקום, הגדילו את דיסק השרת אצל ספק האחסון, ואז הרחיבו את המחיצה ומערכת הקבצים בשרת כך שיראו את הגודל החדש (השלבים תלויים בספק ובתמונת המערכת). אין צורך להתקין מחדש או להגדיר מחדש: ה-API קורא את המקום הפנוי החדש בתוך דקה והמד והגבול עוקבים אחריו.

הודעות צד שלישי#

חבילה זו מריצה את תוכנות הצד השלישי הבאות ללא שינוי, כל אחת בקונטיינר משלה — אלה הודעות, לא ייעוץ משפטי:

• Garage v2.4.1 (אחסון קבצים) — רישיון AGPL-3.0. קוד המקור התואם המלא: https://git.deuxfleurs.fr/Deuxfleurs/garage/src/tag/v2.4.1
• rclone 1.75.1 (הובלת גיבויים) — רישיון MIT. https://github.com/rclone/rclone/tree/v1.75.1
• Caddy v2.11.4 (פרוקסי הפוך / TLS) — רישיון Apache-2.0. https://github.com/caddyserver/caddy/tree/v2.11.4
• PostgreSQL 16.15 (מסד נתונים) — רישיון PostgreSQL. https://www.postgresql.org/ftp/source/v16.15/
• Redis 7.4.11 (מטמון ותורים) — רישיון כפול RSALv2/SSPLv1, לא BSD (Redis שינתה רישיון החל מגרסה 7.4). https://github.com/redis/redis/tree/7.4.11