Lokale Storefront-Domain einrichten

Richten Sie shop.localhost.alvine.dev für eine Site in der Docker-Demo ein. DNS, TLS, DNS-TXT-Verifikation und Site-Domain-Bindung sind danach vorbereitet. Inhalte erscheinen unter der Live-Adresse erst, wenn Sie zusätzlich einen Site Release veröffentlicht haben.

Arbeiten Sie im vorgesehenen Fachmandanten. Eine Tenant Domain gehört nicht in den System-Mandanten und nicht in das Setup-Feld System Domains (CSV). CSV bedeutet dort kommaseparierte Adminhostnamen, nicht Datei-Upload. System-Domains öffnen die Administrationsoberfläche; Tenant Domains gehören einem Mandanten und werden an eine öffentliche Site gebunden.

Voraussetzungen

Sie benötigen:

  • eine bereite Docker-Demo gemäß Docker-Demo in 10 Minuten,
  • einen vollständig provisionierten Mandanten,
  • eine Site im selben Mandanten,
  • nucli mit diesem Mandantenprofil und
  • die erforderlichen Scopes für Sites und Tenant Domains.

Prüfen Sie vor jeder Anlage den aktiven Mandanten im App-Footer:

bash
nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> sites list

Lokales DNS und TLS starten

Das optionale Overlay ergänzt CoreDNS und Caddy. Der normale ./start.sh aktiviert es nicht automatisch.

Starten Sie die Storefront-Befehle im selben Docker-Kontext wie die laufende Basisdemo. Der Wrapper ordnet die Basisruntime über ihren Compose-Service und den lokalen data-Mount eindeutig zu. Dabei übernimmt er Compose-Projekt, Image, Container-UID/GID, öffentliche URL und Adminport. Das gilt auch für Rootless-Runtimes mit hohen Ports. Fehlt die Basisruntime oder passen mehrere laufende Container zum selben data-Verzeichnis, stoppt der Wrapper, ohne ein zweites Compose-Projekt anzulegen.

bash
./storefront-demo/start.sh init
./storefront-demo/start.sh start --detach
./storefront-demo/start.sh status

init erzeugt die lokale CA, das Zertifikat für den Shophost und die DNS-Zone unter data/storefront-demo/. Private Schlüssel besitzen Modus 0600 und bleiben beim Server. Geben Sie weder ca.key noch storefront.key an Browser, CLI-Programme oder Agenten weiter.

Die öffentliche DNS-Zone besitzt Modus 0644, damit der unprivilegierte CoreDNS-Container sie lesen kann. Der Wrapper hebt eine vorhandene Zone beim nächsten Aufruf automatisch von 0600 auf 0644 an. Die privaten Schlüssel bleiben dabei unverändert auf 0600.

Der Host löst über das öffentliche Wildcard-DNS auf 127.0.0.1 auf. Im Compose-Netz liefert CoreDNS den A- und später den TXT-Record. Für den Standardhost benötigen Sie deshalb keine Hosts-Datei.

Tenant Domain verifizieren

Legen Sie die Domain im Fachmandanten mit der Surface cms_public an und starten Sie die Verifikation:

Für die sichere Auswertung benötigt das folgende Bash-Beispiel jq. Führen Sie die Folgeschritte nur aus, wenn der Capture-Block ohne Fehler endet.

bash
nucli --tenant <tenant> web domains create shop.localhost.alvine.dev --surface cms_public --json
if command -v jq >/dev/null 2>&1 &&
  VERIFICATION_JSON="$(nucli --tenant <tenant> web domains start-verification <tenant-domain-id> --json)" &&
  IFS=$'\t' read -r VERIFICATION_TOKEN VERIFICATION_NAME VERIFICATION_VALUE < <(
    jq -er '[.data.token, .data.verificationName, .data.verificationValue] | select(all(.[]; type == "string" and length > 0)) | @tsv' <<<"$VERIFICATION_JSON"
  )
then
  unset VERIFICATION_JSON
  printf 'DNS-Name: %s\nDNS-Wert: %s\n' "$VERIFICATION_NAME" "$VERIFICATION_VALUE"
else
  unset VERIFICATION_JSON VERIFICATION_TOKEN VERIFICATION_NAME VERIFICATION_VALUE
  printf '%s\n' 'Die Verifikationsdaten konnten nicht sicher gelesen werden. Prüfen Sie jq und den nucli-Aufruf.' >&2
  false
fi

verificationName und verificationValue bilden den öffentlichen DNS-Nachweis. Nur der einmalig ausgegebene Roh-Token ist ein geschütztes, kurzlebiges Geheimnis und gehört weder in das Repository noch in Diagnoseprotokolle. Übergeben Sie den TXT-Wert über stdin:

bash
printf '%s\n' "$VERIFICATION_VALUE" | \
  ./storefront-demo/start.sh set-verification \
  --name "$VERIFICATION_NAME" \
  --value-stdin

Prüfen Sie zuerst die lokale Infrastruktur. Fordern Sie die serverseitige DNS-Prüfung danach einmal an:

bash
./storefront-demo/start.sh doctor
printf '%s\n' "$VERIFICATION_TOKEN" | \
  nucli --tenant <tenant> web domains verify-dns <tenant-domain-id> --token-stdin --json
unset VERIFICATION_TOKEN

Die Domain ist verifiziert, wenn verify-dns den erfolgreichen Status meldet. Wiederholen Sie die Prüfung nicht, bevor CoreDNS den neuen TXT-Wert ausliefert.

Domain an die Site binden

bash
nucli --tenant <tenant> web bind-domain <site-id> <tenant-domain-id> --json
nucli --tenant <tenant> web readiness <site-id> --json

Importieren Sie anschließend data/storefront-demo/ca.crt in den Truststore des vorgesehenen Browsers oder Betriebssystems. data/nucleus.crt vertraut dem Adminhost; es stellt das Storefront-Zertifikat nicht aus.

bash
curl --cacert data/storefront-demo/ca.crt -sS -i \
  https://shop.localhost.alvine.dev/

HTTP 404 ist vor dem ersten Live-Release erwartbar. Die Antwort bestätigt in diesem Zustand bereits DNS, TLS und Proxy-Routing. Deaktivieren Sie die Zertifikatsprüfung nicht.

Abweichendes Docker-Subnetz verwenden

Stoppt init wegen eines belegten Subnetzes, wählen Sie ein freies /24 und zwei Adressen daraus:

bash
export STOREFRONT_DEMO_SUBNET=172.30.54.0/24
export STOREFRONT_DEMO_DNS_IP=172.30.54.53
export STOREFRONT_DEMO_PROXY_IP=172.30.54.80
./storefront-demo/start.sh init

Der Wrapper erkennt identische Subnetze. Docker Compose lehnt überlappende Netze ebenfalls ab. Die gewählten Werte bleiben an den initialisierten Laufzeitbestand gebunden.

Wenn Sie DNS- oder HTTPS-Port ändern, verwenden Sie Werte von 1 bis 65535. DNS-, Storefront-HTTPS- und Adminport müssen verschieden sein. Ein bereits zum ermittelten Compose-Projekt gehörendes Storefront-Netz akzeptiert der Wrapper; gleich bezeichnete Netze fremder Projekte bleiben ein Konflikt.

Eigene .test-Domains benötigen einen selbst konfigurierten lokalen DNS-Resolver. Auf NixOS pflegen Sie zusätzliche Hostnamen bei Bedarf deklarativ über networking.extraHosts oder networking.hosts, statt die generierte /etc/hosts dauerhaft von Hand zu ändern.

Ergebnis prüfen

Die lokale Domain ist vorbereitet, wenn:

  • ./storefront-demo/start.sh doctor erfolgreich ist,
  • die Tenant Domain als verifiziert erscheint,
  • die Domain an die richtige Site im selben Mandanten gebunden ist und
  • der HTTPS-Aufruf mit der lokalen CA antwortet.

Ein Preview-Handoff-Link ist ein kurzlebiger Einmal-Token. Öffnen Sie ihn genau einmal im vorgesehenen Browser und übernehmen Sie ihn nicht in Logs oder Testnachweise.

Veröffentlichen Sie anschließend die Site mit CMS-Site prüfen und veröffentlichen. Erst ein veröffentlichter Site Release macht den Inhalt unter der Live-Domain sichtbar.

Nächste Schritte