WindoM
English
מדריך למפתחים

הרצת WindoM מקומית

אפשרות א׳ - התוסף בלבד מומלץ להתחלה#

כך מריצים את התוסף ב-Chrome בלי שום שרת. שעון, מזג אוויר, משימות, רקעים, ציטוטים, קישורים מהירים וטיימר המיקוד עובדים מיד. יומן Google ו-Spotify דורשים את ההתקנה המלאה שלמטה.

דרישות מוקדמות#

שלבים#

1

שכפול המאגר.

git clone https://github.com/YehudaBriskman/WindoM.git cd WindoM
2

התקנת התלויות של התוסף.

cd web npm install
3

בניית התוסף.

npm run build

הפעולה יוצרת תיקיית web/dist/ - זהו התוסף הבנוי.

4

טעינת התוסף ב-Chrome.

  1. פתיחת Chrome ומעבר לכתובת chrome://extensions
  2. הפעלת Developer mode (המתג בפינה הימנית העליונה)
  3. לחיצה על Load unpacked
  4. בחירת התיקייה web/dist
5

פתיחת לשונית חדשה. WindoM אמור להופיע.

מצב פיתוח עם טעינה חוזרת - אפשר להריץ npm run dev במקום build, ואז לטעון את תיקיית השורש web/ (ולא dist/) כתוסף לא ארוז בכתובת chrome://extensions. שינויים נטענים מחדש אוטומטית דרך HMR.

אפשרות ב׳ - מערכת מלאה אופציונלי#

נדרשת אם רוצים סנכרון יומן Google או חיבור ל-Spotify. ההתקנה מריצה שרת מקומי עם בסיס נתונים Postgres באמצעות Docker.

דרישות מוקדמות#

  • כל מה שבאפשרות א׳
  • Docker Desktop
  • פרויקט Google Cloud עם הרשאות OAuth (עבור היומן)
  • אפליקציית Spotify Developer (עבור Spotify)

שלבים#

1

העתקת קובץ הסביבה לדוגמה.

cp backend/.env.example backend/.env

לאחר מכן יש לפתוח את backend/.env ולמלא את הערכים. בטבלת משתני הסביבה שלמטה מוסבר מה כל אחד מהם.

2

יצירת סודות מאובטחים ל-JWT ולהצפנת אסימונים.

node -e "const c=require('crypto'); console.log('JWT_ACCESS_SECRET='+c.randomBytes(32).toString('base64')); console.log('REFRESH_TOKEN_SECRET='+c.randomBytes(32).toString('base64')); console.log('TOKEN_ENC_KEY_BASE64='+c.randomBytes(32).toString('base64'));"

יש להעתיק את הפלט לתוך קובץ ה-.env.

3

הפעלת השרת ובסיס הנתונים עם Docker.

docker-compose up --build

ה-API ירוץ בכתובת http://localhost:8080, ובסיס הנתונים בפורט 5433.

4

בניית התוסף כך שיפנה לשרת המקומי.

cd web npm install npm run build

כתובת השרת כברירת מחדל היא כבר http://localhost:8080, כך שאין צורך בשינויים.

5

טעינת web/dist כתוסף לא ארוז ב-Chrome (זהה לאפשרות א׳, שלב 4).

כתובות חזרה של OAuth - יש להוסיף אותן בקונסולות של אפליקציות ה-OAuth לפני הבדיקה:
  • Google Cloud Console ← Authorized redirect URIs:
    http://localhost:8080/auth/google/callback
    http://localhost:8080/oauth/google/callback
  • Spotify Developer Dashboard ← Redirect URIs:
    http://localhost:8080/oauth/spotify/callback

טבלת משתני הסביבה#

כל המשתנים נכנסים לקובץ backend/.env. אלה המסומנים כלא נדרשים דרושים רק לתכונות מסוימות.

משתנהתיאורנדרש
PORTהפורט שהשרת מאזין בו. ברירת מחדל: 8080לא
DATABASE_URLמחרוזת החיבור ל-Postgres. בהרצה עם Docker Compose היא נקבעת אוטומטית.כן
JWT_ACCESS_SECRETסוד אקראי לחתימת אסימוני גישה. אפשר לייצר עם openssl rand -base64 32כן
REFRESH_TOKEN_SECRETסוד אקראי לחתימת אסימוני רענון. יש לייצר בנפרד מהסוד שלמעלה.כן
TOKEN_ENC_KEY_BASE6432 בתים אקראיים בקידוד base64. משמש להצפנת אסימוני OAuth במנוחה.כן
GOOGLE_CLIENT_IDמזהה לקוח OAuth 2.0 מתוך Google Cloud Console.לתכונות Google
GOOGLE_CLIENT_SECRETסוד לקוח OAuth 2.0 מתוך Google Cloud Console.לתכונות Google
GOOGLE_REDIRECT_URIכתובת חזרה להתחברות עם Google. לדוגמה: http://localhost:8080/auth/google/callbackלתכונות Google
GOOGLE_OAUTH_REDIRECT_URIכתובת חזרה ל-OAuth של יומן Google. לדוגמה: http://localhost:8080/oauth/google/callbackליומן
SPOTIFY_CLIENT_IDמזהה הלקוח מאפליקציית ה-Spotify Developer שלך.ל-Spotify
SPOTIFY_CLIENT_SECRETסוד הלקוח מאפליקציית ה-Spotify Developer שלך.ל-Spotify
SPOTIFY_REDIRECT_URIכתובת חזרה ל-OAuth של Spotify. לדוגמה: http://localhost:8080/oauth/spotify/callbackל-Spotify
CORS_ALLOWED_ORIGINSרשימת מקורות מורשים מופרדת בפסיקים. יש לכלול את מזהה התוסף ואת הפורטים המקומיים.כן
EXTENSION_REDIRECT_BASEכתובת ה-chromiumapp.org של התוסף שלך. משמשת כבסיס ההפניה של OAuth בזרימת ה-identity של Chrome.לתכונות Google
SMTP_HOSTשרת SMTP. ברירת המחדל היא smtp.gmail.com, כך שהשארתו ריק משמרת את התנהגות Gmail. כל ספק עובד - Resend הוא smtp.resend.com, ו-Brevo הוא smtp-relay.brevo.com.לא
SMTP_PORTברירת המחדל היא 465, המשתמש ב-TLS מרומז. פורט 587 מנהל משא ומתן על STARTTLS במקום; הקוד עוקב אחרי הפורט, כך שהשניים נשארים עקביים.לא
SMTP_USERשם המשתמש ל-SMTP. אינו חייב להיות כתובת אימייל - כמה ספקים משתמשים בשם פשוט, למשל resend. אם הוא ו-SMTP_PASS ריקים, הודעות מודפסות לקונסול במקום להישלח.לא
SMTP_PASSסיסמת אפליקציה של Google בת 16 תווים עבור חשבון ה-SMTP. ניתן לייצר בכתובת myaccount.google.com ← Security ← 2-Step Verification ← App Passwords.לא
FROM_EMAILכתובת ה-"From" שמוצגת בהודעות יוצאות. ברירת המחדל היא noreply@windom.app. ב-Gmail היא חייבת להיות SMTP_USER או כינוי מאומת שלו; ספקים ייעודיים דורשים רק שהדומיין יאומת אצלם.לא
APP_URLכתובת הבסיס הציבורית של השרת. משמשת לבניית קישורי אימות אימייל ואיפוס סיסמה. לדוגמה: http://localhost:8080.לא
איתור מזהה התוסף - יש לטעון את התוסף כלא ארוז ב-Chrome ואז לעבור לכתובת chrome://extensions. המזהה מוצג מתחת לשם התוסף. יש להשתמש בו ב-CORS_ALLOWED_ORIGINS בצורה chrome-extension://YOUR_ID וב-EXTENSION_REDIRECT_BASE בצורה https://YOUR_ID.chromiumapp.org.

דוגמה ל-.env לפיתוח מקומי#

הערה על DATABASE_URL - בהרצה עם docker-compose up, הערך של DATABASE_URL נדרס אוטומטית ומצביע על מכולת ה-db (פורט 5432 פנימית). צריך להגדיר אותו ידנית רק אם מריצים את השרת ישירות על המחשב, ואז יש להשתמש בפורט 5433 - הפורט שממופה למארח על ידי Docker Compose.
PORT=8080
NODE_ENV=development
DATABASE_URL=postgresql://windom:windom@localhost:5433/windom
JWT_ACCESS_SECRET=your-generated-secret-here
REFRESH_TOKEN_SECRET=your-other-generated-secret-here
TOKEN_ENC_KEY_BASE64=your-generated-key-here
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8080/auth/google/callback
GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8080/oauth/google/callback
SPOTIFY_CLIENT_ID=your-spotify-client-id
SPOTIFY_CLIENT_SECRET=your-spotify-client-secret
SPOTIFY_REDIRECT_URI=http://localhost:8080/oauth/spotify/callback
CORS_ALLOWED_ORIGINS=chrome-extension://YOUR_EXTENSION_ID,http://localhost:3000,http://localhost:5173
EXTENSION_REDIRECT_BASE=https://YOUR_EXTENSION_ID.chromiumapp.org
# אימייל - אופציונלי. אם יושמט, הודעות אימות ואיפוס מודפסות לקונסול.
# SMTP_USER=you@yourdomain.com
# SMTP_PASS=your-16-char-app-password
# FROM_EMAIL=noreply@windom.app
# APP_URL=http://localhost:8080