Domaini, HTTPS ja välimuurit

Aseta Antimatter domaininimen alle HTTPS:llä käyttäen compose-tiedoston Caddy-profiilia tai omaa välimuuriasi, ja varmista, että sivuston URL-osoite ja asiakasosoitteet ovat oikein.

Sivuston URL-osoite

Sivuston URL-osoite (ServiceSettings.SiteURL) on osoite, jonka kautta ihmiset saavat yhteyden Antimatteriin, esimerkiksi https://chat.example.com. Palvelin käyttää sitä linkkien sisällyttämiseen sähköposteissa ja ilmoituksissa, kirjautumisumppauksissa (OAuth, OpenID Connect, SAML), mobiili- ja pöytätietokone-sovelluksissa sekä pyyntöjen lähtöosoitteen tarkistuksessa. Aseta se täsmälleen sellaiseksi, kuin se näkyy selaimen osoiterivillä: protokolla, domaini ja portti, ellei se ole oletusarvoinen, ilman peräkkäistä kauttaviivaa.

• Sivuston compose-tiedostolla: SITE_URL .env-tiedostossa.
• Muualta: AM_SERVICESETTINGS_SITEURL tai Järjestelmäkonsoli › Ympäristö › Verkkopalvelin › Sivuston URL-osoite.

Jos sivuston URL-osoite on väärin, kirjautuminen identiteettitoimittajan kautta epäonnistuu, sähköpostien linkit osoittavat väärään kohtaan ja sovellukset eivät välttämättä muodosta yhteyttä. Kun domaini on muutettu, päivitä se tähän kohtaan ja kaikkien identiteettitoimittajien umppausosoitteisiin.

HTTPS mukana toimitetulla Caddy-profiililla

Sivuston compose.yaml-tiedosto sisältää Caddy-palvelun https-profiilissa. Se hankkii sertifikaatin Let's Encrypt -palvelusta, uudistaa sen automaattisesti, ohjaa HTTP-liikenteen HTTPS:ään ja välittää kaiken, websocketit mukaan lukien, Antimatteriin.

1. Osoita domainin DNS-tallenne (A, ja AAAA IPv6:n osalta) palvelimeen.
2. Avaa palomuurissa portit 80/tcp, 443/tcp ja 443/udp (HTTP/3). Let's Encrypt -palvelun on päästävä porttiin 80 tai 443 Internetin kautta.
3. Lisää domaini .env-tiedostoon ja aseta sivuston URL-osoite:

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

4. Käynnistä profiililla:

   docker compose --profile https up -d

Lisää --profile https jokaiseen myöhempään docker compose up-komentoon, tai aseta COMPOSE_PROFILES=https .env-tiedostoon, jolloin tavallinen docker compose up -d sisältää sen. Caddy säilyttää sertifikaatit https-volyymissa.

Antimatterin oma portti jätetään julkaistuna isäntäkonetta varten (HTTP_PORT, oletusarvo 8065). Kun Caddy on eteenpäin, pidä se vain palvelinta varten:

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

Caddy pääsee Antimatteriin sisäisen edge-verkkoyhteyden kautta, ei sen portin kautta, joten tämä ei muuta mitkä käyttäjillesi.

Omalla välimuurilla (nginx)

Jos palvelimella on jo nginx tai jokin muu proxy, jätä https-profiili pois ja osoita proxy Antimatterin porttiin 8065. Proxyllä on oltava:

• kyky siirtää websocket-päivitykset (web-sovellus ja mobiilisovellukset pitävät websocket-yhteyden auki osoitteessa /api/v4/websocket, ja jotkin sovellukset avaavat omat yhteytensä);
• hyväksy pyyntöruumiit, jotka ovat vähintään yhtä suuria kuin suurin lähetys (Suurin tiedostokoko, oletusarvo 100 Mt);
• kyky pitää pitkät yhteydet auki (websockets, suuret lähetys- ja latausoperaatiot);
• kyky siirtää Host-otsake ja asiakkaan osoite.

Täydellinen palvelinblokki, joka on mukautettu antimatter-dockerin tuotantopohjasta. Korvaa domainin ja sertifikaattien polut:

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

Tarkista tiedosto komennolla nginx -t ja soita se komennolla systemctl reload nginx. Palvelin lähettää X-Content-Type-Options, Referrer-Policy, Permissions-Policy ja X-Frame-Options -otsakkeet itse; vain HSTS on proxyn hoidettavissa. Nosta sen max-age-arvo, kun HTTPS toimii, ja lisää includeSubDomains vain, jos kaikki alidominit käyttävät HTTPS:ää.

Docker Compose -ympäristössä, jossa nginx on isäntäpalvelimella, yllä oleva upstream osoittaa julkaistuun porttiin 8065. Julkaise se vain osoitteessa 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), jotta kukaan ei ohita proxyä.

antimatter-docker -varastossa on täysi asennus, jossa nginx on kontissa ja Let's Encrypt -sertifikaatit hankitaan certbotin kautta, hakemistossa deploy/compose.

Muut proxyt

Mikä tahansa proxy toimii, jos se täyttää yllä olevat neljä ehtoa. Ääni- ja videopuhelut eivät koskaan kulje proxyä: ne käyttävät omaa porttiansa, ks. Puhelut ja ääni.

Asiakasosoitteet proxyn takana

Proxyn takana jokainen pyyntö näyttää tulevan proxyltä. Jotta todellinen asiakasosoite kirjataan, jotta nopeusrajoituksia voidaan soveltaa asiakaskohtaisesti ja IP-suodatus toimii, on kerrottava palvelimelle, mikä otsake sisältää osoitteen ja mitkä proxyt sille voi luottaa. Molemmissa asetuksissa ei ole kenttää Järjestelmäkonsolissa: aseta ne config.json-tiedostoon tai ympäristömuuttujina.

Muuttujassa erotetaan useat arvot välilyönneillä: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Palvelin hylkää asetukset, joissa TrustedProxyIPs-listassa on arvo, joka ei ole IP-osoite eikä CIDR-alue.

Miten palvelin löytää asiakkaan osoitteen

Jokainen välityspalvelin lisää X-Forwarded-For-otsakkeen oikeaan reunaan osoitteen, josta se sai pyynnin. Asiakkaan itse lähettämä otsake pysyy vasemmalla. Palvelin lukee siis otsakkeen oikealta, ohittaa luotettujen välityspalvelinten osoitteet ja ottaa ensimmäisen muun osoitteen asiakkaan osoitteeksi. Asiakas ei voi valita omaa osoitettaan lähettämällä oman otsakkeen.

• Yhden välityspalvelimen takana TrustedProxyIPHeader riittää saamaan oikean osoitteen: palvelin ottaa otsakkeen oikeanpuoleisin osoitteen. Se kirjaa varoituksen käynnistyksen yhteydessä, kunnes asetat myös TrustedProxyIPs. Ilman sitä kuka tahansa, joka pääsee porttiin 8065 suoraan, voi asettaa otsakkeen, joten julkaise portti vain osoitteessa 127.0.0.1 tai yksityisessä verkossa.
• Useamman välityspalvelimen takana, esimerkiksi CDN:n tai kuormantasaimen edessä, listaa ne kaikki TrustedProxyIPs-asetukseen. Muuten palvelin tulkkaa ulomman välityspalvelimen osoitteen asiakkaan osoitteeksi.
• Välityspalvelin voi joko korvata otsakkeen näkemällään osoitteella, kuten yllä oleva nginx-esimerkki tekee (X-Forwarded-For $remote_addr), tai lisätä siihen (nginx:n $proxy_add_x_forwarded_for). Molemmat toimivat.

Mitä osoitteita listataan

Listaa osoite, josta välityspalvelimen pyynnöt tulevat, Antimatterin näkökulmasta.

• Sivuston compose-tiedostolla ja Caddyllä tämä on jo hoidettu: Caddy pääsee Antimatteriin edge-verkon kautta, ja compose-tiedosto asettaa TrustedProxyIPHeader-asetukseksi X-Forwarded-For ja TrustedProxyIPs-asetukseksi kyseisen verkon alueen, EDGE_SUBNET (172.29.71.0/28, ellei muuta sitä .env-tiedostossa). Muuta EDGE_SUBNET-arvoa, jos se päällekkäin jonkin muun verkkoalueesi kanssa.
• antimatter-dockerin tuotantoympäristön asennus tekee saman nginx-kontteilleen, käyttäen FRONTEND_SUBNET-muuttujaa.
• Kun nginx on isäntakoneella ja Antimatter Docker-kontissa, pyynnöt saapuvat Antimatteriin julkaistun portin kautta, yleensä compose-projektin verkon gateway-osoitteesta (docker network inspect näyttää sen). Aseta AM_SERVICESETTINGS_TRUSTEDPROXYIPS-muuttujaksi se osoite compose.override.yaml-tiedostossa.
• Ilman Dockeriä, kun nginx on samalla isäntakoneella, osoite on 127.0.0.1 (ja ::1, jos nginx käyttää IPv6-yhteyttä).

TLS ilman välityspalvelinta

Palvelin voi myös palvella HTTPS-yhteyksiä itse, kohdassa Järjestelmäkonsoli › Ympäristö › Verkkopalvelin: aseta Yhteyden turvallisuus arvoon TLS (ServiceSettings.ConnectionSecurity) ja määritä TLS-sertifikaattitiedosto sekä TLS-avaintiedosto (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile) tai käytä Käytä Let's Encryptiä (ServiceSettings.UseLetsEncrypt). Tällöin palvelin on kuuntelemassa porttia 443 (Kuunteluosoite, ServiceSettings.ListenAddress, oletusarvo :8065), ja ServiceSettings.Forward80To443 ohjaa portin 80 liikennettä. Vääntöproxy on helpompi ylläpitää ja uudistaa, ja tämä ohje olettaa sen käytön.

Palvelimen aikakatkaisut ja pyyntikoko

Palvelimen oman verkkopalvelimen asetukset, kohdassa Järjestelmäkonsoli › Ympäristö › Verkkopalvelin:

Säilytä proxyllä omat aikakatkaistensa vähintään yhtä pitkänä kuin nämä arvolta tavallisissa pyynnöissä, ja ruumiin koko vähintään Suurin tiedostokoko.