Domains & HTTPS

Von Haus aus ist jedes Projekt über einen Port erreichbar, etwa http://<host>:20000. Das funktioniert, aber merken will man sich das nicht, und viele Anwendungen fühlen sich mit einem richtigen Namen und HTTPS deutlich wohler. Deshalb bringt Envoryx einen Reverse-Proxy mit: Er schaut sich den Hostnamen jeder Anfrage an, schickt sie zum passenden Projekt und liefert nebenbei die Envoryx-Oberfläche aus. Mit ein bisschen Einrichtung heißen deine Projekte dann https://shop.test.

Den Proxy veröffentlichen

Der Proxy lauscht im Container auf den Ports 80 und 443, die beiden müssen also auf den Host. Jeder freie Port tut es; Envoryx liest seine eigenen Port-Bindungen und baut seine Links danach. Die Installation belegt 80/443 - nimm andere, wenn sie schon vergeben sind. Ist keiner der beiden veröffentlicht, warnt Einstellungen → Domains & HTTPS, und die Projektlinks bleiben einfach bei den direkten Ports.

Hat der Container eine eigene IP-Adresse (Unraid br0, macvlan/ipvlan) oder läuft er im Host-Netz, gibt es nichts zu mappen: Der Proxy antwortet direkt auf der Adresse von Envoryx. Deine DNS-Einträge müssen dann auf diese Adresse zeigen.

Namen

Die Basis-Domain ist test, solange du sie unter Einstellungen → Domains & HTTPS nicht änderst. Jedes Projekt heißt dann <slug>.<basis>, die Oberfläche liegt unter envoryx.<basis>. Braucht ein Projekt weitere Namen, etwa shop.local oder api.shop.test, trägst du sie in seinem Bereich Domains ein (oder mit envoryx domain add shop api.shop.test); jeder Name gehört genau einem Projekt.

.test ist eine gute Wahl, weil diese Endung genau dafür reserviert ist und im öffentlichen Internet nie aufgelöst wird. .local sieht verlockend aus, beißt sich unter macOS und Linux aber mit mDNS. Ich würde bei .test bleiben oder eine eigene Domain nehmen, etwa dev.example.com.

DNS: ein Wildcard-Eintrag

Damit shop.test funktioniert, muss jedes Gerät, mit dem du arbeitest, wissen, dass der Name auf deinen Envoryx-Host zeigt. Am einfachsten geht das mit einem Wildcard-Eintrag im DNS-Server deines Netzes. Der deckt alle Projekte ab, die du hast, und auch alle, die noch kommen. Unter Einstellungen → Domains & HTTPS → DNS für *.test zeigt dir Envoryx den passenden Eintrag für deinen DNS-Server, deine Adresse ist schon eingesetzt:

DNS-Server	Eintrag
AdGuard Home	Filters → DNS rewrites: Domain *.test, Antwort <server-ip>
Pi-hole 6	Settings → All settings → Miscellaneous → misc.dnsmasq_lines: address=/test/<server-ip>
Pi-hole 5	/etc/dnsmasq.d/99-envoryx.conf mit address=/test/<server-ip>, dann pihole restartdns
dnsmasq / OpenWrt	address=/test/<server-ip>
Unbound (pfSense, OPNsense)	local-zone: "test." redirect und local-data: "test. IN A <server-ip>"
hosts-Datei	eine Zeile pro Name, z. B. <server-ip> envoryx.test shop.test - für jedes neue Projekt erneut

Manche Router, eine FritzBox zum Beispiel, können gar keine Wildcard-Einträge. Dann bleibt nur die hosts-Datei. Ob alles passt, siehst du unter Einstellungen → Diagnose: Dort prüft dein Browser, ob die Wildcard auflöst und ob das Zertifikat als vertrauenswürdig gilt.

In den Projektcontainern brauchst du nichts davon. Envoryx gibt den Containern alle Proxy-Hostnamen als Netzwerk-Aliase mit, eine Anwendung kann also ihre eigene URL oder die eines anderen Projekts aufrufen. Ein Name, der später dazukommt, ein neues Projekt oder eine gerade hinzugefügte Domain, erreicht die schon laufenden Projekte sofort. Dafür verbindet Envoryx seinen Proxy neu mit jedem Projektnetzwerk, und Verbindungen, die gerade über den Proxy offen sind, reißen dabei kurz ab.

HTTPS mit der lokalen CA

Beim ersten Start legt Envoryx unter /config/ca/ eine eigene kleine Zertifizierungsstelle an und stellt für jeden Hostnamen ein Zertifikat aus, sobald es gebraucht wird. Deine Geräte müssen dieser CA nur einmal vertrauen. Lade sie unter Einstellungen → Domains & HTTPS → envoryx-ca.crt herunterladen herunter und installier sie als vertrauenswürdiges Stammzertifikat; wie das auf den einzelnen Betriebssystemen geht, zeigt dir die Seite. Firefox hat einen eigenen Zertifikatsspeicher und will die CA deshalb extra.

Deine Projektcontainer vertrauen der CA auch ohne all das. Eine Anwendung, die ihre eigene https://shop.test aufruft (ein Webhook, ihre eigene API, ein Cache-Warmer), kommt durch, weil Envoryx ein Bündel aus den üblichen öffentlichen CAs plus seiner eigenen in die Anwendungs- und Worker-Container hängt; Actions, Cron-Jobs und das Terminal haben es also auch. SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE und NODE_EXTRA_CA_CERTS zeigen darauf, und PHP bekommt openssl.cafile und curl.cainfo in seine php.ini. Setzt das Projekt eine dieser Variablen selbst, gilt sein Wert. Java behält seinen eigenen Keystore und ist nicht abgedeckt. Und wenn du ein eigenes Image nutzt, das in seinem eigenen Store schon einer Firmen-CA vertraut: Die steckt nicht in Envoryx’ Bündel. Setz dann SSL_CERT_FILE (und was deine Werkzeuge sonst davon lesen) in der Projektumgebung auf ein Bündel, in dem alles drin ist, was du brauchst.

Ist HTTPS erzwingen an, werden http://-Anfragen für bekannte Namen auf HTTPS umgeleitet.

Achtung

Der CA-Schlüssel kann Zertifikate für jeden Namen signieren. Halte /config privat und installiere die CA nur auf Geräten, die dir gehören.

Let’s Encrypt für deine eigene Domain

Hast du eine eigene Domain, kannst du dir das mit der CA komplett sparen. Envoryx holt sich dann ein öffentliches Wildcard-Zertifikat und verlängert es selbst, und auf keinem Gerät muss etwas installiert werden. Dafür nutzt es die ACME-DNS-Challenge über die API deines DNS-Anbieters - aus dem Internet muss nichts erreichbar sein.

Das klappt mit Cloudflare, Hetzner, netcup, Amazon Route 53, DigitalOcean und Porkbun. Zuerst legst du beim Anbieter API-Zugangsdaten an; bei Cloudflare ist das ein API-Token aus der Vorlage Edit zone DNS, auf die Zone beschränkt. Dann füllst du Einstellungen → Domains & HTTPS → Let’s Encrypt aus: Anbieter, Domain (etwa dev.example.com; die Wildcard *.dev.example.com kommt automatisch dazu), Kontakt-E-Mail und Zugangsdaten, setzt den Haken bei Als Basis-Domain verwenden und aktivierst das Ganze. Zum Schluss leitest du in deinem lokalen DNS *.dev.example.com auf die Adresse von Envoryx. Einen öffentlichen Eintrag legst du dafür nicht an.

Nach ein, zwei Minuten ist das Zertifikat da (netcup und Porkbun lassen sich beim Veröffentlichen etwas mehr Zeit), und 30 Tage vor Ablauf wird es erneuert. Für alle anderen Namen bleibt die lokale CA im Hintergrund. Willst du die Einrichtung erst ausprobieren, nimm die Staging-Option, dann läufst du nicht in Rate-Limits. Hast du schon ein Wildcard-Zertifikat, kannst du es stattdessen samt Schlüssel in derselben Karte hochladen.

Regeln

Unter Domains → Regeln sagst du dem Proxy, was er mit den Anfragen eines Projekts tun soll, bevor deine Anwendung sie überhaupt zu sehen bekommt. Die Regeln gelten für jeden Hostnamen des Projekts und für eine Freigabe. Der direkt veröffentlichte Port geht am Proxy vorbei, dort greifen sie nicht.

Erlaubte Adressen beschränkt das Projekt auf bestimmte Adressen oder Netze, eine pro Zeile (192.168.1.0/24, 10.8.0.5, IPv6 geht auch); alle anderen bekommen ein 403. Steht noch ein Reverse-Proxy davor, sieht die Regel dessen Adresse. Ein Projekt mit so einer Allowlist lässt sich nicht teilen.

Benutzername und Passwort setzt HTTP-Basic-Auth vor das ganze Projekt. Praktisch für eine Staging-Kopie oder eine Freigabe, die du herumschickst. Deine Anwendung bekommt diese Zugangsdaten nie zu sehen.

Weiterleitungen werden der Reihe nach geprüft, der erste Treffer antwortet - mit 302, außer du wählst 301, 307 oder 308. Von ist ein Pfad oder ein Präfix mit * am Ende, und ein Nach mit * am Ende bekommt den Rest des Pfades angehängt. Typischer Fall: www.shop.test /* → https://shop.test/*, damit nur ein Hostname der offizielle ist.

Antwort-Header hängt der Proxy an jede Antwort, zum Beispiel X-Robots-Tag: noindex oder eine Content-Security-Policy. Ein leerer Wert entfernt einen Header - so wirst du etwa X-Powered-By los.

CORS brauchst du, wenn ein Frontend unter einem anderen Hostnamen läuft. Der Proxy beantwortet dann die Preflight-Anfragen der eingetragenen Origins (https://app.test, https://*.shop.test oder *) und setzt die CORS-Header. Setzt du den Haken bei Cookies und Anmeldedaten erlauben, müssen die Origins einzeln eingetragen sein.

Abgearbeitet wird in fester Reihenfolge: Allowlist, HTTPS-Umleitung, CORS-Preflight, Passwort, Weiterleitungen, und erst dann deine Anwendung.

Was deine Anwendung sieht

Der Proxy behält den ursprünglichen Host-Header, setzt X-Forwarded-For, X-Forwarded-Proto und X-Forwarded-Host und reicht WebSockets durch. Deine Anwendung baut damit ohne Zusatzaufwand korrekte absolute URLs. PHP muss sich diese Header nicht einmal ansehen: Weil TLS am Proxy endet, setzt der Webserver des Projekts für Requests, die über https kamen, HTTPS=on, REQUEST_SCHEME=https und den Port des Browsers. Laravel, Symfony, Shopware, TYPO3 und WordPress brauchen deshalb keine Einrichtung vertrauenswürdiger Proxys (mehr dazu auf der PHP-Seite). Muss sie ihre eigene Adresse kennen, steht die in ENVORYX_URL; in einer .env sieht das so aus: APP_URL=${ENVORYX_URL}.

Ein paar Werkzeuge prüfen den Hostnamen selbst: der Dev-Server von Vite, Next.js in der Entwicklung und Drupal. Für Vite lässt Envoryx alles unter deiner Basisdomain durch, und die Templates für Next.js und Drupal tragen die Basisdomain ebenfalls ein, eine zusätzliche Domain wie www.shop.test funktioniert also einfach. Eine eigene Domain außerhalb der Basisdomain musst du dort von Hand nachtragen; wo, steht auf den Seiten zu Node.js und PHP.