From c52186bed02227acdfd864d6b1049c731f06ec68 Mon Sep 17 00:00:00 2001
From: pqhuy1987 <pqhuy1987@gmail.com>
Date: Tue, 21 Apr 2026 21:10:43 +0700
Subject: [PATCH] =?UTF-8?q?[CLAUDE]=20Docs:=20gotcha=20#25=20=E2=80=94=20I?=
 =?UTF-8?q?nstall-WindowsFeature=20Web-WebSockets=20locks=20webSocket=20se?=
 =?UTF-8?q?ction=20in=20applicationHost?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/gotchas.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/gotchas.md b/docs/gotchas.md
index 3235b5a..12ec050 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -182,6 +182,23 @@ Mỗi migration tạo: `{name}.cs` + `{name}.Designer.cs` + `ApplicationDbContex
 
 **Fix:** Luôn dùng `MenuKeys.Contracts` const (BE) + `MenuKeys.Contracts` (FE `menuKeys.ts`). Không hardcode string.
 
+## IIS / Windows Server
+
+### 25. `Install-WindowsFeature Web-WebSockets` khóa section `<webSocket>` ở applicationHost
+
+**Triệu chứng:** Sau khi install WebSocket feature → TẤT CẢ IIS site có `<webSocket enabled="true" />` trong web.config trả về HTTP 500.19 với error code `0x80070021` "configuration section cannot be used at this path" — kể cả site khác project không liên quan.
+
+**Nguyên nhân:** Feature install thêm `<webSocket>` section vào `applicationHost.config` với `overrideModeDefault="Deny"`. Site web.config override section đó → fail.
+
+**Fix:** Unlock section ở server level:
+```powershell
+& "$env:SystemRoot\system32\inetsrv\appcmd.exe" unlock config -section:system.webServer/webSocket
+```
+
+Tương tự khi dùng URL Rewrite `<serverVariables>` cần unlock `system.webServer/rewrite/allowedServerVariables`.
+
+**Cảnh báo co-existence:** Trên VPS shared với project khác, enable feature mới qua `Install-WindowsFeature` có thể làm sập site project khác. Luôn test all site sau mỗi enable.
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat