דומיין, HTTPS ופרוקסי הפוך

העברת Antimatter לדומיין עם HTTPS, באמצעות פרופיל Caddy בקובץ compose או reverse proxy משלך, והגדרת כתובת האתר וכתובות הלקוחות בצורה נכונה.

כתובת האתר (site URL)

כתובת האתר (ServiceSettings.SiteURL) היא הכתובת שבה משתמשים כדי להגיע ל-Antimatter, למשל https://chat.example.com. השרת משתמש בה בקישורים במיילים ובתראות, בהפניות כניסה (OAuth, OpenID Connect, SAML), לאפליקציות המובייל והדסקטופ, ובבדיקת מקור הבקשות. יש להגדיר אותה בדיוק כמו הכתובת בשורת הכתובת של הדפדפן: פרוטוקול, דומיין ופורט אם אינו ברירת המחדל, בלי קו חריץ בסוף.

• עם קובץ compose של האתר: SITE_URL ב-.env.
• בכל מקום אחר: AM_SERVICESETTINGS_SITEURL, או קונסולת מערכת › סביבה › שרת אינטרנט › כתובת האתר (URL).

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

HTTPS עם פרופיל Caddy המצורף

קובץ compose.yaml של האתר כולל שירות Caddy בפרופיל https. הוא מקבל תעודה מ-Let's Encrypt, מתחדש באופן אוטומטי, מפנה מ-HTTP ל-HTTPS ומעביר הכול, כולל websockets, ל-Antimatter.

1. יש להפנות רשומת DNS (A, ו-AAAA עבור IPv6) של הדומיין אל השרת.
2. יש לפתוח את הפורטים 80/tcp, 443/tcp ו-443/udp (HTTP/3) בחומת האש. Let's Encrypt חייב להגיע לפורט 80 או 443 מהאינטרנט.
3. יש להוסיף את הדומיין ל-.env ולהגדיר את כתובת האתר:

   echo "DOMAIN=chat.example.com" >> .env
   sed -i 's|^SITE_URL=.*|SITE_URL=https://chat.example.com|' .env

4. יש להתחיל עם הפרופיל:

   docker compose --profile https up -d

יש להוסיף --profile https לכל docker compose up עתידי, או להגדיר COMPOSE_PROFILES=https ב-.env כדי ש-docker compose up -d רגיל יכלול אותו. Caddy שומר את התעודות שלו ב-https volume.

הפורט של Antimatter עצמו נשאר פתוח על המארח (HTTP_PORT, 8065 כברירת מחדל). עם Caddy מלפנים, יש לשמור אותו עבור השרת בלבד:

echo "HTTP_PORT=127.0.0.1:8065" >> .env
docker compose --profile https up -d

Caddy מגיע ל-Antimatter דרך רשת edge פנימית, לא דרך הפורט הזה, ולכן השינוי אינו משפיע על המשתמשים.

עם reverse proxy משלך (nginx)

אם השרת כבר מריץ nginx או פרוקסי אחר, יש להשאיר את פרופיל https כבוי ולהפנות את הפרוקסי לפורט 8065 של Antimatter. הפרוקסי חייב:

• להעביר שדרוגים של websocket (אפליקציית ה-Web והאפליקציות המובילות שומרות websocket פתוח ב/api/v4/websocket, וחלק מהאפליקציות פותחות websocket משלהן);
• לקבל גופי בקשה (request bodies) בגודל לפחות זהה לגודל ההעלאה הגדול ביותר (גודל קובץ מקסימלי, ברירת המחדל היא 100 MB);
• לשמור חיבורים ארוכי טווח פתוחים (websockets, העלאות והורדות גדולות);
• להעביר את כותרת Host ואת כתובת הלקוח.

בלוק שרת מלא, שהותאם מהתבנית לייצור בantimatter-docker. יש להחליף את הדומיין ואת נתיבי התעודה:

upstream antimatter {
    server 127.0.0.1:8065;
    keepalive 64;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

proxy_cache_path /var/cache/nginx/antimatter levels=1:2 keys_zone=antimatter_cache:10m
                 max_size=3g inactive=120m use_temp_path=off;

server {
    listen 80;
    listen [::]:80;
    server_name chat.example.com;
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name chat.example.com;

    ssl_certificate     /etc/ssl/chat.example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/chat.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_timeout 1d;
    ssl_session_cache shared:AntimatterSSL:10m;
    ssl_session_tickets off;

    add_header Strict-Transport-Security "max-age=31536000" always;

    # At least FileSettings.MaxFileSize (100 MB by default).
    client_max_body_size 100M;

    proxy_http_version 1.1;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        $connection_upgrade;
    proxy_buffers 256 16k;
    proxy_buffer_size 16k;

    location ~ ^/api/v[0-9]+/(users/)?websocket$ {
        client_body_timeout 60s;
        send_timeout 300s;
        lingering_timeout 5s;
        proxy_connect_timeout 90s;
        proxy_send_timeout 300s;
        proxy_read_timeout 90s;
        proxy_pass http://antimatter;
    }

    location / {
        proxy_read_timeout 600s;
        proxy_cache antimatter_cache;
        proxy_cache_revalidate on;
        proxy_cache_min_uses 2;
        proxy_cache_use_stale timeout;
        proxy_cache_lock on;
        proxy_pass http://antimatter;
    }
}

יש לבדוק את הקובץ עם nginx -t ולהחיל אותו עם systemctl reload nginx. השרת שולח בעצמו את X-Content-Type-Options, Referrer-Policy, Permissions-Policy וX-Frame-Options; רק HSTS תלוי בפרוקסי. יש להגדיל את max-age לאחר ש-HTTPS עובד, ולהוסיף includeSubDomains רק אם כל תת-הדומיין משתמש ב-HTTPS.

עם Docker Compose וnginx על המארח, upstream למעלה מצביע על הפורט המפורסם 8065. יש לפרסם אותו ב127.0.0.1 בלבד (HTTP_PORT=127.0.0.1:8065), כדי שאיש לא יוכל לעקוף את הפרוקסי.

במאגר antimatter-docker קיימת הגדרה מלאה עם nginx בתוך קונטיינר ו-Let's Encrypt באמצעות certbot, בdeploy/compose.

פרוקסיות אחרות

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

כתובות לקוחות מאחורי פרוקסי

מאחורי פרוקסי, כל בקשה נראית כאילו היא מגיעה מהפרוקסי. כדי לרשום את כתובת הלקוח האמיתית, להחיל הגבלות קצב לכל לקוח ולנצל סינון כתובות IP, יש להגיד לשרת איזו כותרת נושאת את הכתובת, ואלו פרוקסיות הוא יכול להאמין להן. לשום הגדרה אין שדה בקונסולת מערכת: יש להגדיר אותן בconfig.json או עם משתנים.

במשתנה, מפרידים בין כמה ערכים באמצעות רווחים: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". השרת דוחה הגדרה שבה יש רשומה ב-TrustedProxyIPs שאינה כתובת IP ולא טווח CIDR.

איך השרת מזהה את כתובת הלקוח

כל פרוקסי מוסיף את הכתובת שמהמנה קיבל את הבקשה, מימין ל-X-Forwarded-For. מה שהלקוח שלח בכותרת עצמה נשאר משמאל. לכן השרת קורא את הכותרת מימין, מדלג על כתובות הפרוקסיות המאומנות, ונוטל את הכתובת האחרת הראשונה ככתובת הלקוח. לקוח לא יכול לבחור את כתובתו על ידי שליחת כותרת עצמאית.

• מאחורי פרוקסי אחד, TrustedProxyIPHeader לבדו מספק את הכתובת הנכונה: השרת נוטל את הכתובת הימנית ביותר בכותרת. הוא רושם אזהרה בהתחלה עד שגם את TrustedProxyIPs תגדירו. בלעדיו, כל מי שמגיע ישירות לפורט 8065 יכול להגדיר את הכותרת, לכן פרסמו את הפורט הזה רק על 127.0.0.1 או על רשת פרטית.
• מאחורי כמה פרוקסיות, למשל CDN או מאזן עומס לפני הפרוקסי שלכם, רשמו את כולן ב-TrustedProxyIPs. אחרת, השרת יטעה ויחשוב שהכתובת של הפרוקסי החיצוני היא כתובת הלקוח.
• הפרוקסי יכול להחליף את הכותרת בכתובת שהוא רואה, כפי שעושה דוגמת nginx למעלה (X-Forwarded-For $remote_addr), או להוסיף אליה (ב-nginx: $proxy_add_x_forwarded_for). שני האפשרויות עובדות.

אילו כתובות לרשום

רשמו את הכתובת שממנה מגיעות בקשות הפרוקסי, כפי ש-Antimatter רואה אותה.

• עם קובץ compose של האתר ו-Caddy, זה כבר נעשה: Caddy מתקשר עם Antimatter דרך הרשת edge, וקובץ compose מגדיר את TrustedProxyIPHeader ל-X-Forwarded-For ואת TrustedProxyIPs לטווח של הרשת הזו, EDGE_SUBNET (172.29.71.0/28 אלא אם כן משנים זאת ב-.env). שנו את EDGE_SUBNET אם הוא חופף לאחת מהרשתות שלכם.
• ההגדרה לייצור ב-antimatter-docker עושה את אותו דבר עבור מיכל ה-nginx שלה, באמצעות FRONTEND_SUBNET.
• עם nginx על המארח ו-Antimatter בתוך Docker, הבקשות מגיעות ל-Antimatter דרך הפורט המפורסם, בדרך כלל מכתובת השער של רשת פרויקט compose (docker network inspect מציגה אותה). הגדירו את AM_SERVICESETTINGS_TRUSTEDPROXYIPS לכתובת הזו ב-compose.override.yaml.
• ללא Docker, עם nginx על אותו מארח, זה 127.0.0.1 (וגם ::1 אם nginx מתחבר דרך IPv6).

TLS ללא פרוקסי

השרת יכול גם לשרת HTTPS בעצמו, בקונסולת מערכת › סביבה › שרת אינטרנט: אבטחת חיבור מוגדרת ל-TLS (ServiceSettings.ConnectionSecurity), עם קובץ תעודת TLS וקובץ מפתח TLS (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), או השתמש ב-Let’s Encrypt (ServiceSettings.UseLetsEncrypt). במקרה כזה, השרת חייב להאזין על פורט 443 (כתובת האזנה, ServiceSettings.ListenAddress, ברירת המחדל היא :8065), ו-ServiceSettings.Forward80To443 מעביר את פורט 80. פרוקסי הפוך קל יותר להפעלה ולחידוש, וזה מה שהמדריך הזה מניח.

זמני המתנה של השרת וגודל הבקשות

הגדרות של שרת האינטרנט של השרת עצמו, בקונסולת מערכת › סביבה › שרת אינטרנט:

יש לשמור על זמני המתנה של הפרוקסי עצמו באורך שווה לפחות לאלה עבור בקשות רגילות, ועל גודל הגוף (body) לפחות גודל קובץ מקסימלי.