Domæne, HTTPS og reverse proxies

Sæt Antimatter på et domænenavn med HTTPS, ved hjælp af Caddy-profilen i compose-filen eller en reverse proxy af din egen, og få site-URL og klientadresser til at passe.

Site-URL

Site-URL (ServiceSettings.SiteURL) er den adresse, folk bruger for at nå Antimatter, f.eks. https://chat.example.com. Serveren bruger den i links i e-mails og notifikationer, i login-omretninger (OAuth, OpenID Connect, SAML), til mobil- og desktop-apps, og til at tjekke, hvor anmodninger kommer fra. Sæt den til præcis den adresse, der står i browserens adressefelt: protokol, domæne og port, hvis det ikke er standarden, uden skråstreg i slutningen.

• Med sitets compose-fil: SITE_URL i .env.
• Alle andre steder: AM_SERVICESETTINGS_SITEURL, eller Systemkonsol › Miljø › Webservicer › Site-URL.

Hvis site-URL er forkert, fejler login med en identitetsudbyder, links i e-mails peger på det forkerte sted, og appene kan ikke forbinde. Når du har ændret domænet, skal du opdatere det her og i alle identitetsudbyderes omretnings-URL'er.

HTTPS med den medfølgende Caddy-profil

Sitets compose.yaml indeholder en Caddy-tjeneste i https-profilen. Den henter et certifikat fra Let's Encrypt, forlænger det automatisk, omretter HTTP til HTTPS og videresender alt, inklusive websockets, til Antimatter.

1. Peg et DNS-optegn (A, og AAAA for IPv6) for dit domæne på serveren.
2. Åbn portene 80/tcp, 443/tcp og 443/udp (HTTP/3) i brandmuren. Let's Encrypt skal kunne nå port 80 eller 443 fra internettet.
3. Tilføj domænet til .env og sæt site-URL:

   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

Tilføj --profile https til alle efterfølgende docker compose up-kommandoer, eller sæt COMPOSE_PROFILES=https i .env, så almindelig docker compose up -d inkluderer den. Caddy opbevarer sine certifikater i https-volumen.

Antimatters egen port forbliver udgivet på værten (HTTP_PORT, 8065 som standard). Med Caddy foran, skal den kun bruges af serveren selv:

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

Caddy når Antimatter via det interne edge-netværk, ikke gennem den port, så dette ændrer intet for dine brugere.

Med din egen reverse proxy (nginx)

Hvis serveren allerede kører nginx eller en anden proxy, skal du deaktivere https-profilen og pege proxyen på Antimatters port 8065. Proxyen skal:

• være i stand til at håndtere websocket-opgraderinger (webappen og de mobile apps holder en websocket åben på /api/v4/websocket, og nogle apps åbner deres egne);
• acceptere anmodningskroppe, der mindst er lige så store som den største upload (Maksimal filstørrelse, 100 MB som standard);
• holde langvarige forbindelser åbne (websockets, store uploads og downloads);
• videregive Host-headeren og klientens adresse.

En komplet serverblok, tilpasset fra produktionsmallen i antimatter-docker. Erstat domænet og certificatstierne:

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

Tjek 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 op til proxyen. Øg max-age, når HTTPS fungerer, og tilføj includeSubDomains kun, hvis alle underdomæner bruger HTTPS.

Med Docker Compose og nginx på værten peger upstream ovenfor på den udgivne port 8065. Udgiv den kun på 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), så ingen kan omgå proxyen.

antimatter-docker-repositoryet har en komplet opsætning med nginx i en container og Let's Encrypt via certbot i deploy/compose.

Andre prokser

Enhver proxy fungerer, hvis den opfylder de fire punkter ovenfor. Lyd- og videoopkald går aldrig gennem proxyen: de bruger deres egen port, se Opkald og lyd.

Klientadresser bag en proxy

Bag en proxy ser det ud til, at alle anmodninger kommer fra proxyen. For at logge den reelle klientadresse, anvende hastighedsbegrænsninger pr. klient og bruge IP-filtrering, skal du fortælle serveren, hvilken header der bærer adressen, og hvilke prokser den kan stole på. Ingen af indstillingerne har et felt i Systemkonsolen: sæt dem i config.json eller med variabler.

I en variabel adskiller du flere værdier med mellemrum: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Serveren afviser en konfiguration, der indeholder en post i TrustedProxyIPs, som hverken er en IP-adresse eller et CIDR-område.

Sådan finder serveren klientens adresse

Hver proxy tilføjer den adresse, den modtog anmodningen fra, til højre for X-Forwarded-For. Det, klienten selv sendte i headeren, forbliver til venstre. Serveren læser derfor headeren fra højre, springer adresserne for dine betroede proxs over og tager den første anden adresse som klientens. En klient kan ikke vælge sin egen adresse ved at sende sin egen header.

• Bag én proxy giver TrustedProxyIPHeader alene den korrekte adresse: serveren tager den højremost adresse i headeren. Den logger en advarsel ved opstart, indtil du også sætter TrustedProxyIPs. Uden det kan enhver, der når port 8065 direkte, sætte headeren, så publicér kun den port på 127.0.0.1 eller på et privat netværk.
• Bag flere proxs, for eksempel en CDN eller en load balancer foran din egen proxy, skal du opføre dem alle i TrustedProxyIPs. Ellers tager serveren den yderste proxs adresse for klientens.
• Proxen kan erstatte headeren med den adresse, den ser, som nginx-eksemplet ovenfor gør (X-Forwarded-For $remote_addr), eller tilføje til den (nginxs $proxy_add_x_forwarded_for). Begge dele virker.

Hvilke adresser du skal opføre

Opfør den adresse, proxs anmodninger kommer fra, som Antimatter ser den.

• Med webstedets compose-fil og Caddy er dette allerede gjort: Caddy når Antimatter via edge-netværket, og compose-filen sætter TrustedProxyIPHeader til X-Forwarded-For og TrustedProxyIPs til det netværksområde, EDGE_SUBNET (172.29.71.0/28, medmindre du ændrer det i .env). Ændr EDGE_SUBNET, hvis det overlapper med ét af dine netværk.
• Produktionsopsætningen i antimatter-docker gør det samme for sin nginx-container med FRONTEND_SUBNET.
• Med nginx på værten og Antimatter i Docker når anmodningerne Antimatter gennem den publicerede port, normalt fra gateway-adressen i compose-projektets netværk (docker network inspect viser den). Sæt AM_SERVICESETTINGS_TRUSTEDPROXYIPS til den adresse i compose.override.yaml.
• Uden Docker, men med nginx på samme vært, er det 127.0.0.1 (og ::1, hvis nginx forbinder via IPv6).

TLS uden proxy

Serveren kan også selv levere HTTPS i Systemkonsol › Miljø › Webservicer: Forbindelsessikkerhed sat til TLS (ServiceSettings.ConnectionSecurity), med TLS-certifikatfil og TLS-nøglefil (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), eller Brug Let’s Encrypt (ServiceSettings.UseLetsEncrypt). Serveren skal derefter lytte på port 443 (Lytteadresse, ServiceSettings.ListenAddress, :8065 som standard), og ServiceSettings.Forward80To443 videresender port 80. En reverse proxy er lettere at køre og forlænge, og det er det, denne vejledning forudsætter.

Serverens timeouts og anmodningsstørrelse

Indstillinger for serverens egen webservice, i Systemkonsol › Miljø › Webservicer:

Hold proxyens egne timeouts mindst lige så lange som disse for normale anmodninger, og dens body-størrelse mindst Maksimal filstørrelse.