Doména, HTTPS a reverzní proxy

Umístěte Antimatter na doménové jméno s HTTPS, pomocí profilu Caddy v souboru compose nebo vlastního reverzního proxy, a správně nastavte adresu webu a adresy klientů.

Adresa webu (URL)

Adresa webu (ServiceSettings.SiteURL) je adresa, kterou lidé používají k přístupu k Antimatter, např. https://chat.example.com. Server ji používá v odkazích v e-mailech a oznámeních, při přesměrování při přihlášení (OAuth, OpenID Connect, SAML), pro mobilní a desktopové aplikace a k ověření, odkud požadavky pocházejí. Nastavte ji přesně na adresu v adresním řádku prohlížeče: schéma, doména a port, pokud není výchozí, bez lomítka na konci.

• Pomocí souboru compose webu: SITE_URL v .env.
• Jinde: AM_SERVICESETTINGS_SITEURL, nebo Systémová konzole › Prostředí › Webový server › Adresa webu (URL).

Pokud je adresa webu nesprávná, přihlášení s identitním poskytovatelem selže, odkazy v e-mailech budou ukazovat na špatné místo a aplikace se nemusí připojit. Po změně domény ji aktualizujte zde a v adresách pro přesměrování všech identitních poskytovatelů.

HTTPS s přiloženým profilem Caddy

Soubor compose.yaml webu obsahuje službu Caddy v profilu https. Získá certifikát od Let's Encrypt, obnovuje ho sám, přesměrovává HTTP na HTTPS a předává vše, včetně websocketů, do Antimatter.

1. Nasměrujte záznam DNS (A, a AAAA pro IPv6) vaší domény na server.
2. Otevřete v firewallu porty 80/tcp, 443/tcp a 443/udp (HTTP/3). Let's Encrypt musí mít přístup k portu 80 nebo 443 z internetu.
3. Přidejte doménu do .env a nastavte adresu webu:

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

4. Spusťte s profilem:

   docker compose --profile https up -d

Přidejte --profile https ke každému dalšímu docker compose up, nebo přidejte COMPOSE_PROFILES=https do .env, aby běžné docker compose up -d zahrnulo i tento profil. Caddy si své certifikáty uchovává v objemu https.

Vlastní port Antimatter zůstává publikovaný na hostiteli (HTTP_PORT, výchozí 8065). S Caddy před ním ho ponechte pouze pro samotný server:

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

Caddy se k Antimatter připojuje přes interní síť edge, ne přes tento port, takže se pro vaše uživatele nic nemění.

S vlastním reverzním proxy (nginx)

Pokud server již běží s nginxem nebo jiným proxy, vypněte profil https a nastavte proxy na port 8065 služby Antimatter. Proxy musí:

• přeposílat upgrade na websocket (webová aplikace i mobilní aplikace si drží otevřené websockety na /api/v4/websocket, některé aplikace si navíc otevírají vlastní);
• přijímat těla požadavků nejméně tak velká, jak je největší nahrávka (Maximální velikost souboru, výchozí 100 MB);
• držet dlouhotrvající spojení otevřené (websockety, velké nahrávky a stažení);
• přeposílat hlavičku Host a adresu klienta.

Kompletní blok serveru, upravený z produkční šablony v antimatter-docker. Nahraďte doménu a cesty k certifikátům:

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

Soubor zkontrolujte pomocí nginx -t a použijte ho pomocí systemctl reload nginx. Server sám odesílá hlavičky X-Content-Type-Options, Referrer-Policy, Permissions-Policy a X-Frame-Options; pouze HSTS je na proxy. Jakmile HTTPS funguje, zvýšte její max-age a přidejte includeSubDomains pouze tehdy, pokud všechny subdomény používají HTTPS.

Při použití Docker Compose a nginxu na hostiteli ukazuje výše uvedené upstream na publikovaný port 8065. Publikujte ho pouze na 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), aby nikdo nemohl obejít proxy.

Repozitář antimatter-docker obsahuje kompletní nastavení s nginxem v kontejneru a Let's Encrypt přes certbot, v deploy/compose.

Jiné proxy

Funguje jakékoli proxy, pokud splňuje výše uvedené čtyři body. Hlasové a video hovory nikdy neprocházejí proxy: používají vlastní port, viz Hovory a hlas.

Adresy klientů za proxy

Za proxy se zdá, že každý požadavek pochází z proxy. Aby se logovala skutečná adresa klienta, nastavte serveru, která hlavička nese adresu a kterým proxy může věřit. Žádné z těchto nastavení nemá pole v Systémové konzoli: nastavte je v config.json nebo pomocí proměnných.

V proměnné oddělte více hodnot mezerami: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Server odmítne konfiguraci, která v TrustedProxyIPs obsahuje položku, která není ani IP adresou, ani CIDR rozsahem.

Jak server nachází adresu klienta

Každý proxy přidává na pravou stranu hlavičky X-Forwarded-For adresu, od které požadavek přijal. Adresu, kterou klient sám do hlavičky zadal, ponechá na levé straně. Server tedy hlavičku čte zprava, přeskočí adresy svých důvěryhodných proxy a jako adresu klienta vezme první jinou adresu. Klient si svou adresu nemůže zvolit tím, že pošle vlastní hlavičku.

• Za jedním proxy stačí pro správnou adresu pouze TrustedProxyIPHeader: server vezme nejpravější adresu v hlavičce. Při spuštění vypíše varování, dokud nenastavíte i TrustedProxyIPs. Bez něj by si adresu mohl nastavit kdokoli, kdo se přímě dostane na port 8065, proto tento port zveřejněte pouze na 127.0.0.1 nebo v soukromé síti.
• Za více proxy, například za CDN nebo vyvažovačem zátěže před vlastním proxy, vyjmenujte je všechny v TrustedProxyIPs. Jinak server vezme za adresu klienta adresu vnějšího proxy.
• Proxy může hlavičku nahradit adresou, kterou vidí, jak ukazuje výše uvedený příklad pro nginx (X-Forwarded-For $remote_addr), nebo k ní přidat další hodnotu (nginx $proxy_add_x_forwarded_for). Oba způsoby fungují.

Které adresy vyjmenovat

Vyjmenujte adresu, ze které požadavky proxy pocházejí, tak jak ji vidí Antimatter.

• S compose souborem webu a Caddy je to už hotovo: Caddy se k Antimatteru připojí přes síť edge a compose soubor nastaví TrustedProxyIPHeader na X-Forwarded-For a TrustedProxyIPs na rozsah této sítě, EDGE_SUBNET (pokud ho v .env nezměníte, je to 172.29.71.0/28). Pokud se EDGE_SUBNET překrývá s jednou z vašich sítí, změňte ho.
• Produkční nastavení v antimatter-docker dělá to samé pro svůj nginx kontejner pomocí FRONTEND_SUBNET.
• Pokud běží nginx na hostiteli a Antimatter v Dockeru, požadavky se k Antimatteru dostanou přes zveřejněný port, obvykle z bránové adresy sítě compose projektu (zobrazí ji docker network inspect). V compose.override.yaml nastavte AM_SERVICESETTINGS_TRUSTEDPROXYIPS na tuto adresu.
• Bez Dockeru, s nginxem na stejném hostiteli, je to 127.0.0.1 (a ::1, pokud se nginx připojuje přes IPv6).

TLS bez proxy

Server může HTTPS poskytovat i sám, v Systémová konzole › Prostředí › Webový server: Zabezpečení připojení nastaveno na TLS (ServiceSettings.ConnectionSecurity), s Soubor TLS certifikátu a Soubor TLS klíče (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), nebo Použít Let's Encrypt (ServiceSettings.UseLetsEncrypt). Server se pak musí naslouchat na portu 443 (Adresa naslouchání, ServiceSettings.ListenAddress, výchozí je :8065), a ServiceSettings.Forward80To443 přesměruje port 80. Reverse proxy je jednodušší na provoz a obnovování a je to, co tento průvodce předpokládá.

Časové limity serveru a velikost požadavku

Nastavení vlastního webového serveru, v Systémová konzole › Prostředí › Webový server:

Vlastní časové limity proxy nechte alespoň tak dlouhé jako tyto pro běžné požadavky a její velikost těla alespoň Maximální velikost souboru.