fix: avoid macOS mDNS 5s delay on .local hosts entries

If applied, this commit will make the documented /etc/hosts lines for
the core and stepup environments resolve instantly on macOS instead
of taking ~5 seconds per fresh hostname lookup.

Why is this change needed?
Prior to this change, the /etc/hosts lines had the IP address
followed directly by a real hostname. On macOS, any .local hostname
looked up this way is first tried via multicast DNS (Bonjour), which
times out after ~5 seconds before falling back to /etc/hosts --
regardless of the entry being present. A typical login flow crosses
several *.dev.openconext.local subdomains in sequence, so this tax
stacks up to several seconds per redirect hop.

How does it address the issue?
Adds a throwaway alias word ("oc1"/"oc2") directly after the IP
address on each affected line. A word in that position is enough to
make macOS treat the line as a normal /etc/hosts entry and skip the
mDNS attempt, cutting resolution to milliseconds. Updates both
README.md files and the line init.sh prints during setup, with a
short comment explaining why the leading word is there.

Links / references:
https://www.peterbe.com/plog/make-.local-domains-not-slow-in-macos

Author: kayjoosten

core/README.md

@@ -33,8 +33,11 @@ To start the environment again after the initial setup, a single terminal is suf
 You will also need to tell your local machine where to find the hosts.
 Add the following line in your hosts file (/etc/hosts):
 ```
-127.0.0.1 engine.dev.openconext.local manage.dev.openconext.local profile.dev.openconext.local engine-api.dev.openconext.local mujina-idp.dev.openconext.local profile.dev.openconext.local connect.dev.openconext.local teams.dev.openconext.local voot.dev.openconext.local pdp.dev.openconext.local invite.dev.openconext.local welcome.dev.openconext.local
+127.0.0.1 oc1 engine.dev.openconext.local manage.dev.openconext.local profile.dev.openconext.local engine-api.dev.openconext.local mujina-idp.dev.openconext.local profile.dev.openconext.local connect.dev.openconext.local teams.dev.openconext.local voot.dev.openconext.local pdp.dev.openconext.local invite.dev.openconext.local welcome.dev.openconext.local
 ```
+The leading `oc1` matters on macOS: without a word directly after the IP,
+`.local` hostnames take ~5s to resolve because macOS tries multicast
+DNS (Bonjour) first before falling back to /etc/hosts.
 
 If all goes well, you can now login. Please see the section below to find out where you can login.
 

core/scripts/init.sh

@@ -128,7 +128,10 @@ printf "\n"
 echo -e "${BLUE}Please add the following line to your /etc/hosts: ${VINKJE}"
 printf "\n"
 
-echo "127.0.0.1 engine.dev.openconext.local manage.dev.openconext.local profile.dev.openconext.local engine-api.dev.openconext.local mujina-idp.dev.openconext.local profile.dev.openconext.local connect.dev.openconext.local teams.dev.openconext.local voot.dev.openconext.local invite.dev.openconext.local welcome.dev.openconext.local"
+# The leading "oc1" alias avoids macOS's ~5s mDNS/Bonjour timeout for .local
+# hostnames -- without a word directly after the IP, macOS tries multicast
+# DNS first for every .local lookup before falling back to /etc/hosts.
+echo "127.0.0.1 oc1 engine.dev.openconext.local manage.dev.openconext.local profile.dev.openconext.local engine-api.dev.openconext.local mujina-idp.dev.openconext.local profile.dev.openconext.local connect.dev.openconext.local teams.dev.openconext.local voot.dev.openconext.local invite.dev.openconext.local welcome.dev.openconext.local"
 
 printf "\n"
 echo "You can now login. If you want to bring the environment down, use the command below"

stepup/README.md

@@ -18,8 +18,11 @@ The application config directories contain the SAML key material. Those are not
 First, you need to create an entry in your hosts file (/etc/hosts on *nix systems)
 
 ```
-127.0.0.1 selfservice.dev.openconext.local ssp.dev.openconext.local gateway.dev.openconext.local middleware.dev.openconext.local ra.dev.openconext.local demogssp.dev.openconext.local tiqr.dev.openconext.local webauthn.dev.openconext.local azuremfa.dev.openconext.local
+127.0.0.1 oc2 selfservice.dev.openconext.local ssp.dev.openconext.local gateway.dev.openconext.local middleware.dev.openconext.local ra.dev.openconext.local demogssp.dev.openconext.local tiqr.dev.openconext.local webauthn.dev.openconext.local azuremfa.dev.openconext.local
 ```
+The leading `oc2` matters on macOS: without a word directly after the IP,
+`.local` hostnames take ~5s to resolve because macOS tries multicast
+DNS (Bonjour) first before falling back to /etc/hosts.
 
 Secondly you need to create the `stepup/gateway/surfnet_yubikey.yaml` file with your Yubikey API credentials.
 If you do not have API credentials, you can get them at <https://upgrade.yubico.com/getapikey/>.