Domän, HTTPS och reverse proxies

Placera Antimatter på ett domännamn med HTTPS, med hjälp av Caddy-profilen i compose-filen eller en reverse proxy av ditt eget, och se till att webbadressen och klientadresserna är rätt.

Webbadressen

Webbadressen (ServiceSettings.SiteURL) är den adress som används för att nå Antimatter, till exempel https://chat.example.com. Servern använder den i länkar i e-postmeddelanden och aviseringar, vid inloggningsomdirigeringar (OAuth, OpenID Connect, SAML), för mobil- och skrivbordsapparna, samt för att kontrollera varför begäranden kommer ifrån. Ställ in den till exakt den adress som visas i webbläsarens adressfält: protokoll, domän och port om det inte är standardporten, utan avslutande snedstreck.

• Med webbadressens compose-fil: SITE_URL i .env.
• Annorstans: AM_SERVICESETTINGS_SITEURL, eller Systemkonsol › Miljö › Webserver › Site URL.

Om webbadressen är fel, misslyckas inloggning med en identitetsleverantör, länkar i e-postmeddelanden pekar fel och apparna kan inte ansluta. Efter att du har ändrat domänen, uppdatera den här och i alla identitetsleverantörers omdirigerings-URL:er.

HTTPS med den medföljande Caddy-profilen

Webbadressens compose.yaml innehåller en Caddy-tjänst i https-profilen. Den hämtar ett certifikat från Let's Encrypt, förnyar det automatiskt, omdirigerar HTTP till HTTPS och vidarebefordrar allt, inklusive websockets, till Antimatter.

1. Peaka en DNS-post (A, och AAAA för IPv6) för din domän mot servern.
2. Öppna portarna 80/tcp, 443/tcp och 443/udp (HTTP/3) i brandväggen. Let's Encrypt måste kunna nå port 80 eller 443 från internet.
3. Lägg till domänen i .env och ställ in webbadressen:

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

4. Starta med profilen:

   docker compose --profile https up -d

Lägg till --profile https i varje senare docker compose up, eller sätt COMPOSE_PROFILES=https i .env så att vanlig docker compose up -d inkluderar den. Caddy lagrar sina certifikat i volymen https.

Antimatters egen port förblir publicerad på värdmaskinen (HTTP_PORT, 8065 som standard). Med Caddy framför, behåll den endast för servern själv:

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

Caddy når Antimatter via det interna edge-nätverket, inte genom den porten, så detta ändrar inget för dina användare.

Med din egen reverse proxy (nginx)

Om servern redan kör nginx eller en annan proxy, lämnar du https-profilen av och pekar proxyt mot Antimatters port 8065. Proxyn måste:

• släppa igenom uppgraderingar till websocket (webbappen och mobilapparna håller en websocket öppen på /api/v4/websocket, och vissa appar öppnar egna);
• acceptera anslutningskroppar som är minst lika stora som den största uppladdningen (Maximal filstorlek, 100 MB som standard);
• hålla långlivade anslutningar öppna (websockets, stora uppladdningar och nedladdningar);
• släppa igenom Host-rubriken och klientens adress.

En komplett serverblock, anpassad från produktionsmallen i antimatter-docker. Byt ut domänen och certifikatens sökvägar:

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

Kontrollera filen med nginx -t och tillämpa den med systemctl reload nginx. Servern skickar själv X-Content-Type-Options, Referrer-Policy, Permissions-Policy och X-Frame-Options; endast HSTS är upp till proxyn. Öka dess max-age när HTTPS fungerar, och lägg till includeSubDomains endast om alla underdomäner använder HTTPS.

Med Docker Compose och nginx på värdmaskinen pekar upstream ovan mot den publicerade porten 8065. Publicera den endast på 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), så att ingen kan gå förbi proxyn.

Antimatter-docker-repositoriet har en komplett installation med nginx i en container och Let's Encrypt via certbot, i deploy/compose.

Andra proxyer

Någon proxy fungerar om den uppfyller de fyra punkterna ovan. Ljud- och videosamtal går aldrig genom proxyn: de använder sin egen port, se Samtal och röst.

Klientadresser bakom en proxy

Bakom en proxy verkar varje begäran komma från proxyn. För att logga den verkliga klientadressen, tillämpa hastighetsbegränsningar per klient och använda IP-filter, berätta för servern vilken rubrik som bär adressen, och vilka proxyer den kan lita på. Ingen av inställningarna har ett fält i Systemkonsolen: ställ in dem i config.json eller med variabler.

I en variabel, separera flera värden med mellanslag: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Servern vägrar acceptera en konfiguration där en post i TrustedProxyIPs varken är en IP-adress eller ett CIDR-intervall.

Hur servern hittar klientens adress

Varje proxy lägger till den adress den mottog förfrågan från till höger om X-Forwarded-For. Det som klienten själv skickade i huvudet förblir till vänster. Servern läser därför huvudet från höger, hoppar över adresserna för dina betrodda proxys och tar den första andra adressen som klientens. En klient kan inte välja sin egen adress genom att skicka ett eget huvud.

• Bakom en proxy räcker TrustedProxyIPHeader för att få rätt adress: servern tar den högersta adressen i huvudet. Den loggar en varning vid start tills du också har satt TrustedProxyIPs. Utan det kan alla som når port 8065 direkt sätta huvudet, så publicera den porten endast på 127.0.0.1 eller på ett privat nätverk.
• Bakom flera proxys, till exempel en CDN eller en lastbalansering framför din egen proxy, lista dem alla i TrustedProxyIPs. Annars tar servern den yttre proxyns adress för klientens.
• Proxyn kan antingen ersätta huvudet med den adress den ser, som i nginx-exemplet ovan (X-Forwarded-For $remote_addr), eller lägga till i det (nginxs $proxy_add_x_forwarded_for). Båda fungerar.

Vilka adresser som ska listas

Lista den adress som proxyns förfrågningar kommer ifrån, såsom Antimatter ser den.

• Med webbsajtens compose-fil och Caddy är detta redan gjort: Caddy når Antimatter via edge-nätverket, och compose-filen sätter TrustedProxyIPHeader till X-Forwarded-For och TrustedProxyIPs till det nätverkets intervall, EDGE_SUBNET (172.29.71.0/28 om du inte ändrar det i .env). Ändra EDGE_SUBNET om det överlappar något av dina nätverk.
• Produktionsuppsättningen i antimatter-docker gör detsamma för sin nginx-container, med FRONTEND_SUBNET.
• Med nginx på värdmaskinen och Antimatter i Docker når förfrågningar Antimatter via den publicerade porten, vanligtvis från gateway-adressen i compose-projektets nätverk (docker network inspect visar den). Sätt AM_SERVICESETTINGS_TRUSTEDPROXYIPS till den adressen i compose.override.yaml.
• Utan Docker, med nginx på samma värd, är det 127.0.0.1 (och ::1 om nginx ansluter via IPv6).

TLS utan proxy

Servern kan också själv erbjuda HTTPS, i Systemkonsol › Miljö › Webserver: Anslutningssäkerhet satt till TLS (ServiceSettings.ConnectionSecurity), med TLS Certificate File och TLS Key File (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), eller Använd Let's Encrypt (ServiceSettings.UseLetsEncrypt). Servern måste då lyssna på port 443 (Lyssnaradress, ServiceSettings.ListenAddress, :8065 som standard), och ServiceSettings.Forward80To443 omdirigerar port 80. En reverse proxy är enklare att driva och förnya, och det är vad den här guiden utgår från.

Serverns tidsgränser och storlek på begäranden

Inställningar för serverns egen webserver, i Systemkonsol › Miljö › Webserver:

Håll proxyns egna tidsgränser minst lika långa som dessa för vanliga förfrågningar, och dess kroppsstorlek minst Maximal filstorlek.