Een NGINX Reverse Proxy met SSL instellen voor Umbrel/BTCPay Server

Wil je BTCPay Server op je Umbrel node veilig benaderen via een eigen domein? Deze (mogelijk verouderde - zie update in post!) gids beschrijft hoe ik een NGINX reverse proxy met een gratis Let's Encrypt SSL certificaat heb ingesteld destijds. Stap-voor-stap uitleg over DNS, port forwarding, NGINX configuratie en Certbot.

Draai je persoonlijke Bitcoin en Lightning Network node, host zelf open source apps, schakel tussenpersonen uit en benut het volledige potentieel van Bitcoin. Gratis. — Umbrel

Update (23 mei 2023): Deze gids is bijna twee jaar lang populair geweest! Echter, Umbrel is sindsdien aanzienlijk veranderd. Mensen hebben me laten weten dat deze instructies niet langer direct compatibel zijn. Gebruik deze gids alsjeblieft voor algemene richting en begrip van de concepten, maar volg het niet als exacte stap-voor-stap instructies voor huidige Umbrel-versies.

BTCPay Server draaien op je Umbrel node is fantastisch, maar om het veilig te benaderen van buiten je thuisnetwerk via een eigen domein, vereist wat extra configuratie. Deze gids loopt door hoe ik NGINX heb geconfigureerd als een reverse proxy samen met een gratis Let's Encrypt SSL-certificaat om dat te bereiken.

Benodigdheden

Voordat we beginnen, zorg ervoor dat je het volgende hebt:

  • Een volledig geïnstalleerde en werkende Umbrel node.
  • De BTCPayServer app geïnstalleerd en ingeschakeld via de Umbrel UI.
  • Een eigen domeinnaam waarvan je de DNS kunt beheren.

Voor de voorbeelden hieronder gebruik ik deze placeholder-waarden (vervang ze door je eigen!):

  • Je publieke thuis-IP: 100.100.100.100
  • Umbrel's interne IP: 10.10.10.10
  • Je domeinnaam: jorijn.com
  • Het gewenste subdomein voor BTCPay Server: btcpay.jorijn.com

Stap 1: Je domein naar je thuis-IP laten wijzen

Ga naar het controlepaneel van je domeinregistrar of DNS-provider. Je moet de DNS-zone voor je domein (jorijn.com in mijn voorbeeld) bewerken en een nieuw A-record toevoegen. Dit record moet je gekozen subdomein (btcpay-gedeelte) laten wijzen naar het publieke IP-adres van je thuisnetwerk (100.100.100.100).

Screenshot van een typische DNS-editor die een A-record toont (Voorbeeld: Record Type: A, Naam/Host: btcpay, Waarde/Wijst naar: 100.100.100.100)

Belangrijk: Het kan even duren voordat DNS-wijzigingen wereldwijd zijn doorgevoerd – soms tot 24 uur, maar vaak veel sneller. Ga pas verder als je kunt bevestigen dat de wijziging wereldwijd zichtbaar is.

Stap 2: De DNS-wijziging verifiëren

Je kunt een online tool zoals dnschecker.org gebruiken om te zien of je nieuwe A-record is doorgevoerd.

Voer simpelweg je volledige BTCPay Server domein in (bijv. btcpay.jorijn.com), selecteer 'A' als recordtype, en klik op Search. Je zou je thuis-IP moeten zien verschijnen op de meeste locaties.

https://dnschecker.org/#A/btcpay.jorijn.com

Stap 3: Port forwarding instellen op je router

Om externe toegang mogelijk te maken voor het uitgeven van het SSL-certificaat (Let's Encrypt) en later voor toegang tot BTCPay Server, moeten we specifieke poorten van je internetrouter doorsturen naar het interne IP-adres van je Umbrel node. De exacte stappen hangen sterk af van het merk en model van je router – raadpleeg de handleiding of interface ervan.

Zoek eerst het interne IP-adres van je Umbrel op. Dit vind je meestal in de lijst met verbonden apparaten van je router, of door via SSH in te loggen op Umbrel en een commando zoals ip addr show wlan0 (indien via WiFi) of ip addr show eth0 (indien bekabeld) uit te voeren.

umbrel@umbrel:~ $ ip addr show wlan0
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether dc:a6:32:a4:91:8c brd ff:ff:ff:ff:ff:ff
    inet **10.10.10.10**/24 brd 192.168.121.255 scope global dynamic noprefixroute wlan0
    # [...]

In dit voorbeeld is het interne IP 10.10.10.10.

Maak nu twee port forwarding regels aan in je routerinstellingen:

  1. HTTP Verkeer voor NGINX & Let's Encrypt:
    • Naam: NGINX HTTP (of iets dergelijks)
    • Stuur externe poort 80 (standaard HTTP) door naar Umbrel IP 10.10.10.10 op interne poort 15080.
    • Protocol: TCP
  2. HTTPS Verkeer voor NGINX & Let's Encrypt:
    • Naam: NGINX HTTPS (of iets dergelijks)
    • Stuur externe poort 443 (standaard HTTPS) door naar Umbrel IP 10.10.10.10 op interne poort 15443.
    • Protocol: TCP

(Waarom deze interne poorten? We configureren NGINX later om op 15080 en 15443 te luisteren om conflicten te voorkomen met de hoofdwebserver van Umbrel die intern al 80 en 443 gebruikt).

Stap 4: NGINX & Certbot installeren op Umbrel

Log nu weer via SSH in op je Umbrel node. Het is altijd een goed idee om eerst de pakketlijst bij te werken:

umbrel@umbrel:~ $ sudo apt update
# ... (output weggelaten) ...

Installeer vervolgens NGINX (de reverse proxy) en Certbot (voor Let's Encrypt SSL-certificaten) samen met hun afhankelijkheden:

umbrel@umbrel:~ $ sudo apt install python3-acme python3-certbot python3-mock python3-openssl python3-pkg-resources python3-pyparsing python3-zope.interface python3-certbot-nginx nginx
# ... (output weggelaten) ...

Geen zorgen als de installatie lijkt te mislukken of aan het einde blijft hangen! Dit is verwacht gedrag, omdat de hoofdwebserver van Umbrel intern al poort 80 gebruikt, waar NGINX standaard ook aan probeert te binden.

We moeten NGINX vertellen een andere standaardpoort te gebruiken. Bewerk het standaard NGINX-configuratiebestand:

umbrel@umbrel:~ $ sudo sed -i 's/80 default_server/15080 default_server/g' /etc/nginx/sites-available/default

(Dit commando vervangt 80 default_server door 15080 default_server in het bestand).

Voltooi nu het installatieproces (dit lost meestal afhankelijkheden op en rondt de setup af):

umbrel@umbrel:~ $ sudo apt install -f

Hierna zou je de standaard NGINX welkomstpagina moeten kunnen zien door te browsen naar het interne IP van je Umbrel op poort 15080, bijv. http://10.10.10.10:15080/.

Stap 5: De NGINX-configuratie voor BTCPay Server maken

We moeten NGINX vertellen hoe het verzoeken voor jouw btcpay.jorijn.com domein moet afhandelen en deze moet doorgeven aan de interne BTCPay Server applicatie die op Umbrel draait (die typisch luistert op poort 3003).

Maak een nieuw NGINX-configuratiebestand speciaal voor je BTCPay site:

umbrel@umbrel:~ $ sudo nano /etc/nginx/sites-available/btcpay

Plak de volgende configuratie in de editor. Zorg ervoor dat je btcpay.jorijn.com vervangt door je eigen domein!

# Stel hogere buffer groottes in voor potentieel grote headers/requests van BTCPay Server
proxy_buffer_size          128k;
proxy_buffers              4 256k;
proxy_busy_buffers_size    256k;
client_header_buffer_size 500k;
large_client_header_buffers 4 500k;
http2_max_field_size       500k;
http2_max_header_size      500k;

# Vereist voor WebSocket ondersteuning (gebruikt door BTCPay)
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    # BELANGRIJK: Verander dit naar jouw domein
    server_name btcpay.jorijn.com;

    location / {
        # Stuur verzoeken door naar de interne BTCPay Server app
        proxy_pass [http://127.0.0.1:3003](http://127.0.0.1:3003);

        # Stel headers in om correcte informatie door te geven aan BTCPay
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # Luister op de interne poort die we eerder hebben doorgestuurd (voor HTTP)
    listen 15080;
    listen [::]:15080; # Luister ook op IPv6

    # SSL configuratie wordt hier later door Certbot toegevoegd
}

Sla het bestand op (CTRL+O in nano, dan Enter) en sluit de editor (CTRL+X).

Activeer nu deze nieuwe configuratie door een symbolische link te maken:

umbrel@umbrel:~ $ sudo ln -s /etc/nginx/sites-available/btcpay /etc/nginx/sites-enabled/

Test of je NGINX-configuratie syntax nog steeds correct is:

umbrel@umbrel:~ $ sudo nginx -t
# Verwacht output zoals: nginx: configuration file /etc/nginx/nginx.conf test is successful

Als de test succesvol is, herlaad NGINX om de nieuwe configuratie toe te passen:

umbrel@umbrel:~ $ sudo systemctl reload nginx.service

Stap 6: Je SSL-certificaat aanvragen met Certbot

Nu gebruiken we Certbot om automatisch een gratis SSL-certificaat van Let's Encrypt te verkrijgen en NGINX te configureren om het te gebruiken voor HTTPS.

Voer het volgende commando uit, en vervang btcpay.jorijn.com door jouw domein en jorijn@jorijn.com door jouw e-mailadres (Let's Encrypt gebruikt dit voor verlengingsherinneringen).

umbrel@umbrel:~ $ sudo certbot --nginx -d btcpay.jorijn.com -m jorijn@jorijn.com --agree-tos --no-eff-email --tls-sni-01-port 15443 --http-01-port 15080
  • --nginx: Gebruik de NGINX plugin om NGINX automatisch te configureren.
  • -d: Specificeer de domeinnaam.
  • -m: Jouw e-mailadres.
  • --agree-tos: Ga akkoord met de Let's Encrypt Servicevoorwaarden.
  • --no-eff-email: Optioneel: Vermijd inschrijving op de EFF nieuwsbrief.
  • --tls-sni-01-port 15443: Vertel Certbot om validatie-uitdagingen uit te voeren via de interne HTTPS-poort die we eerder hebben doorgestuurd.
  • --http-01-port 15080: Vertel Certbot om indien nodig de interne HTTP-poort te gebruiken voor validatie.

Certbot zal waarschijnlijk vragen of je HTTP-verkeer wilt doorsturen naar HTTPS. Kies voor nu optie 1: No redirect. We configureren dit handmatig in de volgende stap voor betere controle.

Indien succesvol, zal Certbot melden dat het certificaat is geïmplementeerd en je NGINX-configuratie is bijgewerkt.

Stap 7: Handmatig de HTTP-naar-HTTPS redirect toevoegen

Om ervoor te zorgen dat alle bezoekers de beveiligde HTTPS-verbinding gebruiken, voegen we handmatig een redirect-regel toe. Dit dwingt al het verkeer dat binnenkomt op de onbeveiligde poort 15080 voor jouw domein om te worden doorgestuurd naar de beveiligde poort 15443 (die je router doorstuurt vanaf 443).

Open je BTCPay NGINX configuratiebestand opnieuw:

umbrel@umbrel:~ $ sudo nano /etc/nginx/sites-available/btcpay

Certbot zou regels moeten hebben toegevoegd met betrekking tot SSL en luisteren op poort 15443 binnen het oorspronkelijke server { ... } blok. We moeten een nieuw server blok toevoegen onder het bestaande blok om de redirect af te handelen.

Plak het volgende blok aan het einde van het bestand. Vergeet niet om btcpay.jorijn.com tweemaal te vervangen door jouw domein!


# Dit nieuwe server blok handelt de redirect af
server {
    listen 15080;
    listen [::]:15080;

    # BELANGRIJK: Verander dit naar jouw domein
    server_name btcpay.jorijn.com;

    # Als de host overeenkomt, stuur permanent door naar HTTPS
    if ($host = btcpay.jorijn.com) {
        return 301 https://$host$request_uri;
    }

    # Geef 404 terug voor andere verzoeken op deze poort (optioneel maar goede praktijk)
    return 404;
}

Sla het bestand op (CTRL+O, Enter) en sluit af (CTRL+X).

Test ten slotte de configuratie opnieuw en herlaad NGINX:

umbrel@umbrel:~ $ sudo nginx -t
# Verwacht succesbericht
umbrel@umbrel:~ $ sudo systemctl reload nginx.service

Dat is alles! Je BTCPay Server zou nu veilig toegankelijk moeten zijn via HTTPS op je eigen domein, bijv. https://btcpay.jorijn.com/.

De Betaalknop en verder

Nu NGINX het domein en SSL afhandelt, zou BTCPay Server automatisch de juiste embed-codes (zoals de Pay Button code) moeten genereren met jouw https://btcpay.jorijn.com domein. Je kunt deze uit je BTCPay Server interface halen en integreren in je website.

Hopelijk helpt deze gids je om je eigen veilige setup op te zetten! Onthoud dat deze gids mogelijk verouderd is voor de nieuwste Umbrel-versies, dus pas aan waar nodig.