Local IIS Setup for *.raklet.org¶

This guide sets up your local machine to serve any *.raklet.org subdomain via IIS — no need to manually add hosts file entries per subdomain.

Prerequisites¶

Windows 10/11 with IIS enabled
IIS 10+ (supports wildcard host headers)
SQL Server Express at LOCALHOST\SQLEXPRESS
The v3 IIS site pointing to C:\repos\rakletv3\Application

1. SSL Certificate¶

A self-signed wildcard certificate for *.raklet.org must be installed in the LocalMachine\My store and bound to 0.0.0.0:443 in IIS.

To check if it's already present:

Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Subject -like "*raklet*" }

If missing, generate and install one:

$cert = New-SelfSignedCertificate -DnsName "*.raklet.org" -CertStoreLocation "Cert:\LocalMachine\My"

Then bind it in IIS Manager: Default Web Site → Bindings → HTTPS → select the wildcard cert — or via PowerShell:

Import-Module WebAdministration
$thumb = (Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Subject -like "*raklet*" }).Thumbprint
New-Item "IIS:\SslBindings\0.0.0.0!443" -Value (Get-Item "Cert:\LocalMachine\My\$thumb")

2. IIS Site Bindings¶

The v3 site needs wildcard bindings on both HTTP and HTTPS. Run once to set up:

Import-Module WebAdministration

# Wildcard bindings — catch any *.raklet.org subdomain
New-WebBinding -Name "v3" -Protocol "http"  -Port 80  -HostHeader "*.raklet.org"
New-WebBinding -Name "v3" -Protocol "https" -Port 443 -HostHeader "*.raklet.org"

Verify:

Get-WebBinding -Name "v3" | Sort-Object protocol, bindingInformation | Format-Table protocol, bindingInformation -AutoSize

You should see at minimum:

protocol  bindingInformation
--------  ------------------
http      *:80:*.raklet.org
https     *:443:*.raklet.org

Note: Individual hostname bindings (e.g. demo1.raklet.org) are redundant once the wildcard binding is in place, but they coexist harmlessly.

3. Wildcard DNS — Acrylic DNS Proxy¶

The Windows hosts file does not support wildcards. Acrylic DNS Proxy fills this gap.

Install¶

winget install Mayakron.AcrylicDNS

Configure wildcard rule¶

Open C:\Program Files (x86)\Acrylic DNS Proxy\AcrylicHosts.txt and add at the bottom:

127.0.0.1 >raklet.org

The > prefix is Acrylic shorthand for "match raklet.org and all *.raklet.org subdomains."

Start the service¶

sc.exe start AcrylicDNSProxySvc

Point your network adapter to Acrylic¶

# Replace "Ethernet" with your adapter name if different (check with: ipconfig)
netsh interface ip set dns "Ethernet" static 127.0.0.1 primary
netsh interface ip add dns "Ethernet" 168.63.129.16 index=2   # fallback — use your normal DNS here

Azure VMs (e.g. CI-VM-1): the adapter's DNS can revert to the Azure platform resolver 168.63.129.16 (after network re-config, agent install, etc.). When it does, Acrylic is bypassed: hosts-file-pinned subdomains still work, but any new *.raklet.org slug not in the hosts file leaks to public DNS, lands on the real Azure app, and the browser shows a *.azurewebsites.net cert (NET::ERR_CERT_COMMON_NAME_INVALID). It looks like a cert bug; it's DNS. Re-point the adapter (PowerShell equivalent, persists across reboot):
Set-DnsClientServerAddress -InterfaceAlias "Ethernet 10" -ServerAddresses ("127.0.0.1","168.63.129.16")
Clear-DnsClientCache
Acrylic forwards everything else to its own upstreams (8.8.8.8/8.8.4.4 by default in AcrylicConfiguration.ini), so making it primary does not break general DNS. Browsers cache DNS separately — restart the browser or clear chrome://net-internals/#dns after re-pointing.

Verify wildcard resolution is working:

nslookup anythingnew.raklet.org 127.0.0.1
# Should return 127.0.0.1

4. Restart IIS¶

iisreset

5. Organization must exist in the database¶

IIS and DNS will route any *.raklet.org request to the app, but the app looks up the subdomain as an organisation permalink in the database. If the org doesn't exist, you'll get a 404.

SELECT Permalink, Name FROM Organisations

To test with a specific subdomain (e.g. demo1.raklet.org), the Organisations table must have a row with Permalink = 'demo1'. Create it via the admin panel or insert directly.

DB-backed Raklet.UnitTests that need an organisation fixture read their local override from Raklet.UnitTests/App.config:

<add key="OrganisationMembershipCrudTests-Permalink" value="demo" />

Set this value to the organisation permalink that exists in your local RakletV3 database, such as your personal *.raklet.org organisation. Release/test environments should keep using an organisation fixture that exists in that environment, such as demo on .raklet.net.

Troubleshooting¶

Symptom	Likely cause
DNS not resolving `*.raklet.org` to `127.0.0.1`	Acrylic service not running or adapter DNS not set to `127.0.0.1`
SSL certificate error in browser	Self-signed cert not trusted — add to `Trusted Root Certification Authorities` store
Browser shows a `.azurewebsites.net` cert / `NET::ERR_CERT_COMMON_NAME_INVALID` for a new* subdomain	Adapter DNS drifted off Acrylic (`127.0.0.1`) back to `168.63.129.16`, so the slug leaked to public DNS → real Azure app. Re-point the adapter (see Step 3 Azure-VM note). It's DNS, not a cert.
HTTP 404 from the app	Organisation with that permalink doesn't exist in the database
Entire site returns "We are upgrading"	`_app_offline.htm` exists in `C:\repos\rakletv3\Application\` — delete it
IIS returns 404 for all requests	Wildcard binding missing — re-run Step 2