Setting Up Local HTTPS with Caddy Reverse Proxy for Next.js JSS

Running your Next.js + Sitecore JSS stack under HTTPS locally isn’t just about flashing a padlock icon—it keeps API contracts, cookies, and OAuth flows behaving exactly like they do in production. Below is the full workflow I use to stand up https://localdev.corp.test on Windows with Caddy and mkcert. Swap in your own domain as needed.

---

🧩 Prerequisites

• Windows 10/11 with Administrator rights
• Chocolatey (Windows package manager)
• Node.js LTS, Caddy, mkcert, Git, VS Code

Already have Chocolatey and some tools? Great—just skip whatever’s installed and keep moving.

---

📦 1. Install Chocolatey

Chocolatey makes the rest of the tooling painless.

1. Launch PowerShell as Administrator.
2. Run:

   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
   

3. Confirm it worked:

   choco -v
   

---

🧱 2. Install Your Toolchain

With Chocolatey ready, pull down everything in one shot (still in elevated PowerShell):

choco install nodejs-lts mkcert caddy git vscode -y

Feel free to trim that list if you already have Git or VS Code.

---

🔒 3. Generate Local Certificates

Certs live alongside the project so Caddy can reference them.

cd C:\Projects\pennent-xm-cloud\gigya-local-setup
mkcert -install
mkcert localdev.corp.test

You’ll get:

• localdev.corp.test.pem
• localdev.corp.test-key.pem

Keep both inside gigya-local-setup.

---

🧠 4. Map the Domain in hosts

Point your custom domain at localhost (IPv4 and IPv6).

1. Open Notepad as Administrator.
2. Edit C:\Windows\System32\drivers\etc\hosts.
3. Append:

   127.0.0.1   localdev.corp.test
   ::1         localdev.corp.test
   

4. Save and flush DNS:

   ipconfig /flushdns
   

---

🛑 5. Free Up Ports 80/443

Caddy won’t start if IIS (or anything else) has those ports locked.

Stop-Service W3SVC -Force
Set-Service W3SVC -StartupType Manual
netstat -ano | findstr ":80 "
netstat -ano | findstr ":443 "

If something’s still listening, track the PID and stop it:

Stop-Process -Id <PID> -Force

---

🧾 6. Author the Caddyfile

Create a file literally named Caddyfile in C:\Projects\pennent-xm-cloud\gigya-local-setup:

localdev.corp.test:443 {
    tls localdev.corp.test.pem localdev.corp.test-key.pem
    reverse_proxy localhost:3000
}

• localhost:3000 → where your Next.js/Sitecore JSS dev server runs
• localdev.corp.test → the domain you mapped in hosts

---

🚀 7. Run Caddy

From the same directory:

cd C:\Projects\pennent-xm-cloud\gigya-local-setup
caddy run --config Caddyfile

Look for a log line similar to:

http.log        server running  {"name": "srv0", "protocols": ["h1", "h2", "h3"]}

That’s Caddy reverse-proxying HTTPS traffic to your dev server.

---

✅ 8. Test the Site

Fire up your Next.js app (npm run dev) and load https://localdev.corp.test in the browser. You should see:

• Your local Sitecore JSS experience
• A trusted certificate (padlock + “Connection is secure”)

---

🧹 9. Optional: Format the Caddyfile

Caddy can tidy and lint its own config:

caddy fmt --overwrite Caddyfile

---

🔁 10. Troubleshooting Cheat Sheet

Problem	Why it happens	Quick fix
Access denied on port 80/443	IIS or another listener is running	Stop IIS with Stop-Service W3SVC -Force
Browser still warns “Not secure”	Trust store missing mkcert root	Re-run mkcert -install
Caddyfile warnings	Formatting or syntax issues	caddy fmt --overwrite Caddyfile
Domain won’t resolve	Hosts file wasn’t saved as admin	Re-open Notepad as admin, save again

---

🔄 11. After Every Reboot

1. Stop IIS (Stop-Service W3SVC -Force).
2. Start your Next.js app (npm run dev).
3. Launch Caddy (caddy run --config Caddyfile).
4. Visit https://localdev.corp.test.

Repeat whenever you restart your machine or swap branches.

---

🧭 Summary

Component	Why it matters
Chocolatey	Fast install + upgrades for Windows tooling
mkcert	Trusted local certificates with zero manual import steps
Caddy	Handles HTTPS termination and reverse proxying
Hosts file	Routes localdev.corp.test to 127.0.0.1
IIS stop	Keeps ports 80/443 open so Caddy can bind

Result: your Next.js + Sitecore JSS environment is available at https://localdev.corp.test with a fully trusted padlock, no surprises.

---