Domene, HTTPS og reverse proxies

Plasser Antimatter på et domenenavn med HTTPS, ved hjelp av Caddy-profilen i compose-filen eller en reverse proxy du har selv, og sørg for at nettside-URL-en og klientadressene er riktige.

Nettside-URL-en

Nettside-URL-en (ServiceSettings.SiteURL) er adressen folk bruker for å nå Antimatter, for eksempel https://chat.example.com. Serveren bruker den i lenker i e-poster og varsler, i omdirigeringer ved pålogging (OAuth, OpenID Connect, SAML), for mobil- og skrivebordsappene, og for å sjekke hvor forespørsler kommer fra. Still inn nøyaktig adressen i nettleserens adressefelt: protokoll, domene og port hvis ikke standard, uten skråstrek i slutten.

• Med nettsidens compose-fil: SITE_URL i .env.
• Et annet sted: AM_SERVICESETTINGS_SITEURL, eller Systemkonsoll › Miljø › Nettserver › Nettsteds-URL.

Hvis nettside-URL-en er feil, vil pålogging med en identitetsleverandør mislykkes, lenker i e-poster peke til feil sted, og appene kan ikke koble til. Etter å ha endret domenet, oppdater det her og i omdirigerings-URL-ene for alle identitetsleverandører.

HTTPS med den medfølgende Caddy-profilen

Nettsidens compose.yaml inneholder en Caddy-tjeneste i https-profilen. Den henter et sertifikat fra Let's Encrypt, fornyer det automatisk, omdirigerer HTTP til HTTPS og videresender alt, inkludert websockets, til Antimatter.

1. Pek en DNS-post (A, og AAAA for IPv6) for domenet mot serveren.
2. Åpne portene 80/tcp, 443/tcp og 443/udp (HTTP/3) i brannmuren. Let's Encrypt må kunne nå port 80 eller 443 fra internett.
3. Legg til domenet i .env og still inn nettside-URL-en:

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

4. Start med profilen:

   docker compose --profile https up -d

Legg til --profile https i alle senere docker compose up-kommandoer, eller legg inn COMPOSE_PROFILES=https i .env slik at vanlig docker compose up -d inkluderer den. Caddy lagrer sertifikatene sine i https-volumet.

Antimatters egen port forblir utgitt på vertsmaskinen (HTTP_PORT, 8065 som standard). Med Caddy foran, behold den kun for selve serveren:

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

Caddy når Antimatter over det interne edge-nettverket, ikke gjennom den porten, så dette endrer ingenting for brukerne dine.

Med din egen reverse proxy (nginx)

Hvis serveren allerede kjører nginx eller en annen proxy, slår du av https-profilen og peker proxyen mot Antimatters port 8065. Proxyen må:

• la WebSocket-opgraderinger passere (nettappet og mobilappene holder en WebSocket åpen på /api/v4/websocket, og noen apper åpner sine egne);
• akseptere forespørselskropper som er minst like store som den største opplastingen (Maksimal filstørrelse, 100 MB som standard);
• holde langlevende tilkoblinger åpne (WebSockets, store opplastinger og nedlastinger);
• la Host-hodet og klientens adresse passere.

Et komplett serverblokk, tilpasset fra produksjonsmalen i antimatter-docker. Bytt ut domenet og sertifikatstiene:

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

Sjekk filen med nginx -t og anvend den med systemctl reload nginx. Serveren sender X-Content-Type-Options, Referrer-Policy, Permissions-Policy og X-Frame-Options selv; kun HSTS er opp til proxyen. Øk max-age når HTTPS fungerer, og legg til includeSubDomains bare hvis alle underdomener bruker HTTPS.

Med Docker Compose og nginx på verten, peker upstream ovenfor mot den utgitte porten 8065. Gi den ut kun på 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), slik at ingen kan omgå proxyen.

antimatter-docker-repositoriet har en fullstendig oppsett med nginx i en container og Let's Encrypt via certbot, i deploy/compose.

Andre proxyer

Enhver proxy fungerer hvis den oppfyller de fire punktene ovenfor. Audio- og videotaler går aldri gjennom proxyen: de bruker sin egen port, se Samtaler og tale.

Klientadresser bak en proxy

Bak en proxy ser alle forespørsler ut til å komme fra proxyen. For å logge den egentlige klientadressen, anvende hastighetsbegrensninger per klient og bruke IP-filtrering, må du fortelle serveren hvilket hode som bærer adressen, og hvilke proxyer den kan stole på. Ingen av disse innstillingene har et felt i Systemkonsollen: sett dem i config.json eller med variabler.

I en variabel, separer flere verdier med mellomrom: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Serveren avviser en konfigurasjon som har en post i TrustedProxyIPs som verken er en IP-adresse eller et CIDR-område.

Hvordan serveren finner klientens adresse

Hver proxy legger adressen den mottok forespørselen fra til høyre for X-Forwarded-For. Det klienten selv sendte i overskriften forblir til venstre. Serveren leser derfor overskriften fra høyre, hopper over adressene til de tillitede proxyene, og bruker den første andre adressen som klientens. En klient kan ikke velge sin egen adresse ved å sende sin egen overskrift.

• Bak én proxy gir TrustedProxyIPHeader alene rett adresse: serveren bruker den ytterste adressen i overskriften. Den logger en advarsel ved oppstart inntil du også setter TrustedProxyIPs. Uten dette kan alle som når port 8065 direkte sette overskriften, så publiser kun den porten på 127.0.0.1 eller på et privat nettverk.
• Bak flere proxyer, for eksempel en CDN eller en lastbalanser foran din egen proxy, må du liste dem alle i TrustedProxyIPs. Ellers tar serveren den ytre proxyens adresse for klientens.
• Proxyen kan erstatte overskriften med adressen den ser, som nginx-eksemplet over gjør (X-Forwarded-For $remote_addr), eller legge til i den (nginxs $proxy_add_x_forwarded_for). Begge deler fungerer.

Hvilke adresser du skal liste

List adressen proxyens forespørsler kommer fra, slik Antimatter ser den.

• Med nettstedets compose-fil og Caddy er dette allerede gjort: Caddy når Antimatter via edge-nettverket, og compose-filen setter TrustedProxyIPHeader til X-Forwarded-For og TrustedProxyIPs til det nettverkets område, EDGE_SUBNET (172.29.71.0/28 med mindre du endrer det i .env). Endre EDGE_SUBNET hvis det overlapper med ett av dine nettverk.
• Produksjonsoppsettet i antimatter-docker gjør det samme for nginx-beholderen, med FRONTEND_SUBNET.
• Med nginx på vertsmaskinen og Antimatter i Docker, når forespørsler Antimatter gjennom den publiserte porten, vanligvis fra gateway-adressen til compose-projektets nettverk (docker network inspect viser den). Sett AM_SERVICESETTINGS_TRUSTEDPROXYIPS til den adressen i compose.override.yaml.
• Uten Docker, med nginx på samme vert, er det 127.0.0.1 (og ::1 hvis nginx kobler til via IPv6).

TLS uten en proxy

Serveren kan også selv levere HTTPS, i Systemkonsoll › Miljø › Nettserver: Forbindelsessikkerhet satt til TLS (ServiceSettings.ConnectionSecurity), med TLS-sertifikatfil og TLS-nøkkel (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), eller Bruk Let's Encrypt (ServiceSettings.UseLetsEncrypt). Serveren må da lytte på port 443 (Lyttadresse, ServiceSettings.ListenAddress, :8065 som standard), og ServiceSettings.Forward80To443 videresender port 80. En omvendt proxy er enklere å kjøre og fornye, og er det denne veiledningen forutsetter.

Serverens tidsavbrudd og størrelse på forespørsler

Innstillinger for serverens egen nettserver, i Systemkonsoll › Miljø › Nettserver:

Hold proxyens egne tidsbegrensninger minst like lange som disse for vanlige forespørsler, og størrelsen på kroppen minst Maksimal filstørrelse.