Domein, HTTPS en reverse proxies

Plaats Antimatter op een domeinnaam met HTTPS, gebruik het Caddy-profiel in het compose-bestand of een reverse proxy naar keuze, en stel de site-URL en de clientadressen correct in.

De site-URL

De site-URL (ServiceSettings.SiteURL) is het adres dat mensen gebruiken om bij Antimatter te komen, zoals https://chat.example.com. De server gebruikt dit in links in e-mails en meldingen, bij inlogomleidingen (OAuth, OpenID Connect, SAML), voor de mobiele en desktop apps en om te controleren waar verzoeken vandaan komen. Stel dit in op exact het adres in de adresbalk van de browser: protocol, domein en poort (indien niet de standaard), zonder schuine streep aan het einde.

• Met het compose-bestand van de site: SITE_URL in .env.
• Elders: AM_SERVICESETTINGS_SITEURL, of Systeem console › Omgeving › Webserver › Site URL.

Als de site-URL onjuist is, mislukt het inloggen met een identiteitsprovider, wijzen links in e-mails naar de verkeerde plek en kunnen de apps mogelijk geen verbinding maken. Na het wijzigen van het domein, werk dit hier en in de omleidings-URL’s van elke identiteitsprovider bij.

HTTPS met het meegeleverde Caddy-profiel

Het compose.yaml-bestand van de site bevat een Caddy-service in het https-profiel. Deze haalt een certificaat op bij Let's Encrypt, vernieuwt het automatisch, leidt HTTP om naar HTTPS en doorgeeft alles, inclusief websockets, door naar Antimatter.

1. Wijzig een DNS-record (A, en AAAA voor IPv6) van uw domein zodat het naar de server wijst.
2. Open poorten 80/tcp, 443/tcp en 443/udp (HTTP/3) in de firewall. Let's Encrypt moet poort 80 of 443 vanuit het internet kunnen bereiken.
3. Voeg het domein toe aan .env en stel de site-URL in:

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

4. Start met het profiel:

   docker compose --profile https up -d

Voeg --profile https toe aan elk latere docker compose up, of zet COMPOSE_PROFILES=https in .env zodat een gewoon docker compose up -d het meeneemt. Caddy bewaart zijn certificaten in de https-volume.

De eigen poort van Antimatter blijft op de host gepubliceerd (HTTP_PORT, standaard 8065). Met Caddy ervoor, houd deze alleen voor de server zelf:

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

Caddy bereikt Antimatter via het interne edge-netwerk, niet via die poort, dus dit verandert niets voor uw gebruikers.

Met uw eigen reverse proxy (nginx)

Als de server al nginx of een andere proxy draait, laat het https-profiel uit en wijs de proxy door naar poort 8065 van Antimatter. De proxy moet:

• websocket-upgrades doorgeven (de webapp en de mobiele apps houden een websocket open op /api/v4/websocket, en sommige apps openen er zelf een);
• aanvraaglichamen accepteren die minstens zo groot zijn als de grootste upload (Maximale bestandsgrootte, standaard 100 MB);
• langlevende verbindingen open houden (websockets, grote uploads en downloads);
• de Host-header en het adres van de client doorgeven.

Een complete serverblok, aangepast aan het productietemplate in antimatter-docker. Vervang het domein en de paden naar de certificaten:

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

Controleer het bestand met nginx -t en pas het toe met systemctl reload nginx. De server stuurt zelf X-Content-Type-Options, Referrer-Policy, Permissions-Policy en X-Frame-Options; alleen HSTS is aan de proxy overgelaten. Verhoog de max-age zodra HTTPS werkt, en voeg includeSubDomains alleen toe als alle subdomeinen HTTPS gebruiken.

Bij Docker Compose en nginx op de host, wijst de upstream hierboven naar de gepubliceerde poort 8065. Publiceer deze alleen op 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), zodat niemand de proxy kan omzeilen.

De antimatter-docker-repository bevat een volledige installatie met nginx in een container en Let's Encrypt via certbot, in deploy/compose.

Andere proxies

Elke proxy werkt als deze aan de vier punten hierboven voldoet. Audio- en videoverzoeken gaan nooit via de proxy: ze gebruiken hun eigen poort, zie Gesprekken en spraak.

Clientadressen achter een proxy

Achter een proxy lijkt elk verzoek afkomstig te zijn van de proxy. Om het echte clientadres te loggen, tariefbeperkingen per client toe te passen en IP-filtering te gebruiken, moet u de server vertellen welke header het adres bevat en welke proxies hij kan vertrouwen. Voor geen van beide instellingen is er een veld in de Systeemconsole: stel ze in via config.json of met variabelen.

Scheid in een variabele meerdere waarden met spaties: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". De server weigert een configuratie waarin TrustedProxyIPs een item bevat dat noch een IP-adres noch een CIDR-bereik is.

Hoe de server het adres van de client bepaalt

Elke proxy voegt het adres waarvandaan het verzoek is ontvangen toe aan het rechterkant van X-Forwarded-For. Wat de client zelf in de header heeft gezet, blijft links staan. De server leest de header dus van rechts naar links, slaat de adressen van uw vertrouwde proxies over en neemt het eerste andere adres als het adres van de client. Een client kan zijn eigen adres niet kiezen door een eigen header te sturen.

• Achter één proxy geeft TrustedProxyIPHeader alleen al het juiste adres: de server neemt het meest rechter adres in de header. Totdat u ook TrustedProxyIPs instelt, logt de server een waarschuwing bij het opstarten. Zonder deze instelling kan iedereen die rechtstreeks poort 8065 bereikt de header instellen. Publiceer die poort daarom alleen op 127.0.0.1 of op een privé-netwerk.
• Achter meerdere proxies, bijvoorbeeld een CDN of een load balancer voor uw eigen proxy, vermeldt u ze allemaal in TrustedProxyIPs. Anders neemt de server het adres van de buitenste proxy als het adres van de client.
• De proxy kan de header vervangen door het adres dat hij ziet, zoals in het nginx-voorbeeld hierboven (X-Forwarded-For $remote_addr), of het adres toevoegen (nginx's $proxy_add_x_forwarded_for). Beide methodes werken.

Welke adressen u vermeldt

Vermeld het adres waarvandaan de verzoeken van de proxy komen, zoals Antimatter het ziet.

• Met de compose-bestand van de site en Caddy is dit al geregeld: Caddy bereikt Antimatter via het edge-netwerk, en het compose-bestand stelt TrustedProxyIPHeader in op X-Forwarded-For en TrustedProxyIPs op het bereik van dat netwerk, EDGE_SUBNET (standaard 172.29.71.0/28, tenzij u het wijzigt in .env). Wijzig EDGE_SUBNET als het overlapt met een van uw netwerken.
• De productiesetup in antimatter-docker doet hetzelfde voor de nginx-container, met FRONTEND_SUBNET.
• Bij nginx op de host en Antimatter in Docker bereiken verzoeken Antimatter via de gepubliceerde poort, meestal vanuit het gateway-adres van het netwerk van het compose-project (docker network inspect toont dit). Stel AM_SERVICESETTINGS_TRUSTEDPROXYIPS in op dat adres in compose.override.yaml.
• Zonder Docker, met nginx op dezelfde host, is het 127.0.0.1 (en ::1 als nginx via IPv6 verbinding maakt).

TLS zonder proxy

De server kan ook zelf HTTPS aanbieden, in Systeem console › Omgeving › Webserver: Beveiliging verbinding(en) ingesteld op TLS (ServiceSettings.ConnectionSecurity), met TLS-certificaatbestand en TLS-sleutelbestand (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), of Gebruik Let's Encrypt (ServiceSettings.UseLetsEncrypt). De server moet dan luisteren op poort 443 (Luister Adres, ServiceSettings.ListenAddress, standaard :8065), en ServiceSettings.Forward80To443 leidt poort 80 om. Een reverse proxy is makkelijker te onderhouden en te vernieuwen, en is wat deze handleiding veronderstelt.

Server-time-outs en verzoekgrootte

Instellingen van de eigen webserver van de server, in Systeem console › Omgeving › Webserver:

Houd de eigen time-outs van de proxy minstens zo lang als deze voor normale verzoeken, en de body-grootte minstens Maximale bestandsgrootte.