הדרכות מפורטות

Python

בדוגמה שלנו ב-Python נעשה שימוש ב-framework של Flask. אפשר להוריד את קוד המקור המלא מהקישורים שמופיעים כאן.

אם צריך, מתקינים Python 3.7 ואילך ומוודאים ש-pip זמין.

python3 -m ensurepip --upgrade

מומלץ גם להגדיר ולהפעיל סביבה וירטואלית חדשה של Python.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

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

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

בדוגמה שלנו ל-Node.js נעשה שימוש ב-Express framework. אפשר להוריד את קוד המקור המלא מהקישורים שצוינו.

בדוגמה הזו נדרשת Node.js v16.13 ואילך.

מתקינים את מודולי הצומת הנדרשים באמצעות npm.

npm install

Java

בדוגמה שלנו ל-Java נעשה שימוש ב-Spring Boot framework. אפשר להוריד את קוד המקור המלא מהקישורים שצוינו.

אם Java 11+‎ עדיין לא מותקנת במחשב, מתקינים אותה.

אפליקציות Spring Boot יכולות להשתמש ב-Gradle או ב-Maven כדי לטפל בבנייה ולנהל תלות. הדוגמה הזו כוללת את Maven wrapper, שדואג לבנייה מוצלחת בלי שתצטרכו להתקין את Maven עצמו.

בספרייה שבה הפרויקט הורד או שוכפל, מריצים את הפקודות הבאות כדי לוודא שיש לכם את הדרישות המוקדמות להרצת הפרויקט.

java --version
./mvnw --version

או ב-Windows:

java -version
mvnw.cmd --version

Python

• ספריית הבסיס מכילה את הקבצים הבאים:

  • ‫main.py – נקודת הכניסה לאפליקציית Python. מציינים בקובץ את תצורת השרת שרוצים להשתמש בה, ואז מריצים אותו כדי להפעיל את השרת.
  • ‫requirements.txt – מודולי Python שנדרשים להרצת אפליקציית האינטרנט. אפשר להתקין אותם באופן אוטומטי באמצעות pip install -r requirements.txt.

  • ‫client_secret.json – קובץ סוד הלקוח שהורדתם מ-Google Cloud. שימו לב שהקובץ הזה לא נכלל בארכיון לדוגמה. צריך לשנות את השם של קובץ ההרשאות שהורד ולהעתיק אותו לכל תיקיית בסיס.

• ‫config.py – אפשרויות הגדרה לשרת Flask.

• בספרייה webapp נמצא התוכן של אפליקציית האינטרנט. היא כוללת את הפריטים הבאים:

• ספריית /templates/ עם תבניות Jinja לדפים שונים.

• הספרייה /static/ עם תמונות, CSS וקובצי JavaScript משניים.

• ‫routes.py – שיטות הטיפול במסלולים של אפליקציית האינטרנט.

• ‫__init__.py – הפונקציה לאתחול המודול webapp. הפונקציה הזו מפעילה את שרת Flask וטוענת את אפשרויות ההגדרה שמוגדרות ב-config.py.

• קבצים נוספים לפי הצורך בשלב מסוים בתהליך.

Node.js

כל שלב בהדרכה מופיע בתיקיית משנה משלו <step>. כל שלב מכיל:

• קבצים סטטיים כמו JavaScript, ‏ CSS ותמונות נמצאים בתיקייה ./<step>/public.
• נתבי Express נמצאים בתיקיות ./<step>/routes.
• תבניות HTML נמצאות בתיקיות ./<step>/views.
• אפליקציית השרת היא ./<step>/app.js.

Java

ספריית הפרויקט כוללת את הפריטים הבאים:

• הספרייה src.main מכילה את קוד המקור ואת ההגדרות להרצת האפליקציה בהצלחה. הספרייה הזו כוללת את הפריטים הבאים: + הספרייה java.com.addons.spring מכילה את הקבצים Application.java ו-Controller.java. הקובץ Application.java אחראי להפעלת שרת האפליקציות, והקובץ Controller.java אחראי ללוגיקה של נקודת הקצה. ‫+ הספרייה resources מכילה את הספרייה templates עם קובצי HTML ו-JavaScript. הוא מכיל גם את הקובץ application.properties שמציין את היציאה להרצת השרת, את הנתיב לקובץ מאגר המפתחות ואת הנתיב לספרייה templates. בדוגמה הזו, קובץ מאגר המפתחות נמצא בספרייה resources. אפשר לאחסן אותו בכל מקום שרוצים, אבל חשוב לעדכן את הנתיב בקובץ application.properties בהתאם.
  • ‫pom.xml מכיל את המידע שנדרש כדי לבנות את הפרויקט ולהגדיר את התלות הנדרשת.
  • ‫.gitignore מכיל שמות של קבצים שאסור להעלות ל-git. חשוב להוסיף את הנתיב למאגר המפתחות ב-.gitignore. בדוגמה שמופיעה למעלה, זהו secrets/*.p12 (הסבר על המטרה של מאגר המפתחות מופיע בקטע הבא). במדריכים 2 ואילך, צריך לכלול גם את הנתיב לקובץ client_secret.json כדי לוודא שלא תכללו את הסודות שלכם במאגר מרוחק. במדריכים 3 ואילך, צריך להוסיף את הנתיב לקובץ מסד הנתונים H2 ואת המפעל של מאגר הנתונים של הקובץ. מידע נוסף על ההגדרה של מאגרי הנתונים האלה זמין במדריך השלישי בנושא טיפול בביקורים חוזרים.
  • ‫mvnw ו-mvnw.cmd הם קובצי ההפעלה של Maven Wrapper ל-Unix ול-Windows, בהתאמה. לדוגמה, הפעלת הפקודה ./mvnw --version ב-Unix מפיקה את גרסת Apache Maven, בין שאר הפרטים.
  • הספרייה .mvn מכילה את ההגדרות של Maven Wrapper.

Python

פרטי כניסה של OAuth

יוצרים ומורידים את פרטי הכניסה בפרוטוקול OAuth כפי שמתואר קודם. ממקמים את קובץ ה-JSON בספריית השורש לצד קובץ ההפעלה של השרת של האפליקציה.

הגדרת השרת

יש כמה אפשרויות להפעלת שרת האינטרנט. בסוף קובץ ה-Python, מוסיפים את אחת מהשורות הבאות:

1. לא מאובטח localhost. הערה: האפשרות הזו מתאימה לבדיקה ישירה רק בחלון דפדפן. אי אפשר לטעון דומיינים לא מאובטחים ב-iframe של תוסף Classroom.

   if __name__ == "__main__":
     # Disable OAuthlib's HTTPs verification.
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
   
     # Run the web app at http://localhost:5000.
     app.run(debug=True)
   

2. מאובטח localhost. צריך לציין טאפל של קובצי מפתח SSL לארגומנט ssl_context.

   if __name__ == "__main__":
     # Run the web app at https://localhost:5000.
     app.run(host="localhost",
             ssl_context=("localhost.pem", "localhost-key.pem"),
             debug=True)
   

3. שרת Gunicorn. האפשרות הזו מתאימה לשרת שמוכן לייצור או לפריסה בענן. מומלץ להגדיר משתנה סביבה PORT לשימוש באפשרות ההפעלה הזו.

   if __name__ == "__main__":
     # Run the web app at https://<your domain>:<server_port>.
     # Defaults to https://<your domain>:8080.
     server_port = os.environ.get("PORT", "8080")
     app.run(debug=True, port=server_port, host="0.0.0.0")
   

הפעלת השרת

מריצים את אפליקציית Python כדי להפעיל את השרת כפי שהוגדר בשלב הקודם.

python main.py

לוחצים על כתובת ה-URL שמופיעה כדי לראות את אפליקציית האינטרנט בדפדפן ולוודא שהיא פועלת בצורה תקינה.

Node.js

הגדרת השרת

כדי להפעיל את השרת באמצעות HTTPS, צריך ליצור אישור עצמי שמשמש להפעלת האפליקציה באמצעות HTTPS. צריך לשמור את פרטי הכניסה האלה כ-sslcert/cert.pem וכ-sslcert/key.pem בתיקיית הבסיס של המאגר. יכול להיות שתצטרכו להוסיף את המפתחות האלה למחזיק המפתחות של מערכת ההפעלה כדי שהדפדפן יקבל אותם.

מוודאים שהקובץ *.pem נמצא בקובץ .gitignore כי לא רוצים לבצע commit של הקובץ ל-git.

הפעלת השרת

אפשר להריץ את האפליקציה באמצעות הפקודה הבאה, ולהחליף את step01 בשלב הנכון שרוצים להריץ כשרת (לדוגמה, step01 עבור 01-basic-app ו-step02 עבור 02-sign-in).

npm run step01

או

npm run step02

הפעולה הזו תפעיל את שרת האינטרנט בכתובת https://localhost:5000.

אפשר להפסיק את השרת באמצעות הפקודה Control + C במסוף.

Java

הגדרת השרת

כדי להפעיל את השרת באמצעות HTTPS, צריך ליצור אישור עצמי שמשמש להפעלת האפליקציה באמצעות HTTPS.

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

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

בדוגמה הזו, קובץ מאגר המפתחות נמצא בספריית המשאבים. אפשר לאחסן אותו בכל מקום שרוצים, אבל חשוב לעדכן את הנתיב בקובץ application.properties בהתאם. שם הדומיין הוא הדומיין שבו הפרויקט פועל (לדוגמה, localhost).

מוודאים שהקובץ *.p12 נמצא בקובץ .gitignore כי לא רוצים לבצע commit של הקובץ ל-git.

הפעלת השרת

מפעילים את השרת על ידי הרצת ה-method‏ main בקובץ Application.java. לדוגמה, ב-IntelliJ אפשר ללחוץ לחיצה ימנית על Application.java > Run 'Application' בספרייה src/main/java/com/addons/spring, או לפתוח את הקובץ Application.java וללחוץ על החץ הירוק שמימין לחתימת השיטה main(String[] args). אפשר גם להריץ את הפרויקט בחלון של מסוף:

./mvnw spring-boot:run

או ב-Windows:

mvnw.cmd spring-boot:run

השרת יופעל בכתובת https://localhost:5000 או ביציאה שצוינה ב-application.properties.