EDFI-2779: Restructure the Windows IIS installation guide - #537
Merged
analiliagutierrez merged 14 commits intoJul 31, 2026
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Admin App v4 documentation to align the Windows/IIS installation path with the current installation scripts and to clarify database/hosting expectations across Windows, Unix-like, and Docker Compose deployment options.
Changes:
- Rewrites the Windows IIS installation guide around httpPlatform hosting, TLS-by-default, least-privilege DB access, and the scripted vs. manual install flows.
- Refreshes troubleshooting guidance to match the new IIS/httpPlatform deployment model and adds targeted frontend IIS troubleshooting (e.g., missing
.woff2MIME types). - Clarifies configuration and security guidance (OIDC
<oidc-id>usage, encryption key format, outbound TLS verification, and security headers expectations).
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/5-admin-app/troubleshooting.md | Replaces iisnode-focused troubleshooting with httpPlatform/IIS + TLS-by-default troubleshooting guidance. |
| docs/reference/5-admin-app/readme.md | Adds direct links to key Admin App doc sections (configuration/troubleshooting/maintenance). |
| docs/reference/5-admin-app/maintenance.md | Adjusts update guidance to prefer stable release tags over main. |
| docs/reference/5-admin-app/getting-started/windows-iis-installation.md | Major rewrite to match current Windows install scripts (ports, TLS, httpPlatform, Keycloak example, uninstall guidance). |
| docs/reference/5-admin-app/getting-started/unix-installation.md | Clarifies Postgres-only expectations for the Unix-like path and updates encryption-key guidance. |
| docs/reference/5-admin-app/getting-started/readme.md | Updates the “choose one path” framing and refines reverse-proxy guidance/wording. |
| docs/reference/5-admin-app/getting-started/docker-installation.md | Adds explicit DB engine selection instructions and clarifies NODE_EXTRA_CA_CERTS usage. |
| docs/reference/5-admin-app/configuration/security-considerations.md | Expands security guidance to reflect IIS path defaults and built-in protections across install paths. |
| docs/reference/5-admin-app/configuration/identity-provider.md | Updates redirect URI guidance to use <oidc-id> and clarifies it is not always 1. |
| docs/reference/5-admin-app/configuration/configuring-admin-app.md | Updates configuration reference examples (encryption key format, OIDC table name, outbound TLS verification, and related notes). |
analiliagutierrez
force-pushed
the
EDFI-2779_Windows_Server_Installation_Guide
branch
2 times, most recently
from
July 17, 2026 16:24
0a003f7 to
65033a2
Compare
adiaz-msdf
reviewed
Jul 17, 2026
adiaz-msdf
left a comment
adiaz-msdf
left a comment
Contributor
There was a problem hiding this comment.
#Review of PR #537 (docs)
Suggestion: split the Windows IIS guide into three pages (Manual / Automated / Semi-automated)
The rewrite is a big content upgrade, but the page has also grown a lot, and it now serves three different readers at once — someone who just wants install-all.ps1, someone doing everything by hand, and someone mixing the two. As a reader I found it hard to tell at any given point whether I was looking at a manual step or at a description of what a script does: the "Fast path" table, the "Run everything at once" section, the :::tip Automation shortcut callouts, and the manual numbered steps all interleave on one page, so every reader ends up scanning past content meant for a different path.
Proposal: turn Windows IIS Installation into a small landing page plus three focused pages:
- Windows IIS Installation (Automated) — the shortest page:
setup-vm-prereqs.ps1on a fresh VM, theninstall-all.ps1with the parameter examples, idempotent re-run flags (-SkipPhase1/-SkipPhase2), and first sign-in. No manual steps at all. - Windows IIS Installation (Manual) — the current manual numbered steps, with no script references inline: prerequisites, database, IdP, both deployments,
web.configlistings,production.js. This becomes the authoritative "what actually gets configured" reference. - Windows IIS Installation (Semi-automated) — essentially the current script↔section mapping table, for people who automate some sections and hand-configure others (e.g., scripts for prereqs and build, manual deploy against an existing IIS setup). Each row links to the corresponding manual section on page 2.
If a multi-page split is too big a change for this PR, a lighter fallback would be <Tabs> (Automated / Manual) within each section — but I think separate pages read better for content this long, and search/deep-links land the reader on the right path.
Contributor
Author
Thank you, I think your suggestion makes total sense. I'll work on these changes. |
analiliagutierrez
marked this pull request as ready for review
July 20, 2026 15:49
Rewrite the Windows IIS installation guide to match the current Admin App v4 install scripts: two IIS sites over HTTPS (API and frontend) with HTTP redirects, the httpPlatform handler replacing iisnode, aligned web.config and production.js/.env, TLS by default with a self-signed fallback, and scripted and manual paths documented side by side. Adds a runnable install-all.ps1 example and a first sign-in note.
State which database engine each installation path supports: the Docker Compose stack (both engines, PostgreSQL by default, SQL Server via DB_ENGINE=mssql and the -MSSQL switch) and the Unix path (PostgreSQL).
Bring the reference pages in line with what the v4 install scripts deploy: - Troubleshooting rewritten from iisnode to the httpPlatform hosting model. - configuring-admin-app: fix the ENABLE_OPEN_API key, correct the DB encryption key length (64 hex chars), de-duplicate the frontend build-time variables, and fix the OIDC config table name. - OIDC callback URIs use the configured provider id. - Security "Built-in Protections" made installer-neutral; maintenance now updates via a release tag instead of git pull. - Minor consistency fixes across getting-started, readme, docker, and unix (self-signed cert note, encryption-key example, 500.19 references).
The Database engine section appears before the guide establishes a working directory, so reference the script as compose/start-services.ps1 -MSSQL rather than ./start-services.ps1 -MSSQL.
…pages Restructure the single Windows IIS installation page into a category: a landing overview plus Automated, Semi-automated, and Manual pages. The Manual page is the authoritative, script-free reference (prerequisites, both IIS sites, the exact web.config and production.js); Automated and Semi-automated cover the install-all.ps1 script paths. Repoint the inbound links and anchors from the other Admin App docs to the new pages.
Add a note to the Windows IIS Automated page that the examples must be run as-is (each Read-Host -AsSecureString prompts for the value at the console; do not substitute literal passwords), and point to the scripts repository's windows-install/README.md and Get-Help for the full parameter list.
Add an interim warning to the manual (Windows/IIS), Docker, and Unix Admin App install guides telling operators to use only URL-safe characters in the database password until the source fix ships.
The install now bootstraps SQL Server under Windows Authentication and connects only as the least-privilege edfi_adminapp login, so the guide no longer enables or uses sa.
Windows Server 2019/2022 do not ship winget, which the scripts require. Add a prerequisite section (official Microsoft install links plus an optional community helper) to the automated path and a pointer from the semi-automated path.
Use "Web Application" for the frontend site, spell out abbreviations (database, PostgreSQL, virtual machine, operating-system, identity provider), and clarify that install-all.ps1 can run without parameters. No functional changes.
The guide did not say where to clone the scripts, even though install-all.ps1 places the Admin App source beside them, so the resulting layout was left to chance. It also predated the scheduled task that brings the local Keycloak back after a host restart, and stated the IIS requirement only in passing. Correct three problems found while reviewing those additions: - The install-all.ps1 examples passed only parameters the script already prompts for, so they demonstrated nothing. One example remains, showing just the PostgreSQL parameters that are not prompted for. - The manual TLS step pointed at New-Item IIS:\SslBindings, which is unavailable outside Windows PowerShell. IIS Manager, already used by the binding steps, covers it. - The manual guide asked the reader to resolve the oidc row id before the API had created that row. It now says to register 1 and to confirm the id once the API has started. Also promote the manual First sign-in note to a section ahead of Uninstall, point the prerequisite overview at its own subsections, and drop wording that repeated itself.
analiliagutierrez
force-pushed
the
EDFI-2779_Windows_Server_Installation_Guide
branch
from
July 30, 2026 03:18
feceb42 to
ad2b6b2
Compare
Keycloak is the only fully supported provider in this release. Microsoft Entra ID and Google Workspace have been tested and gain full support in Admin App v4.1. Drops the stale claim that no other provider has been tested, and the "in theory any OIDC-compatible IdP will suffice" hedge.
Replaces the category's _category_.json with sidebar_position in its readme, the mechanism the rest of the repo uses. The label now comes from the page H1, which is identical to the one the JSON set, and the rendered sidebar order is unchanged.
adiaz-msdf
approved these changes
Jul 30, 2026
analiliagutierrez
deleted the
EDFI-2779_Windows_Server_Installation_Guide
branch
July 31, 2026 16:05
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the Windows IIS installation guide to match the current Admin App v4 install scripts and aligns the surrounding reference docs with what the scripts actually deploy (HTTPS by default, httpPlatform hosting, least-privilege DB login, enforcing security headers). Also clarifies which database engine each installation path supports.
Tickets
What changed
Windows IIS guide (EDFI-2779) — rewritten to match the scripts:
:3443, FE:4443), HTTP bindings redirect; httpPlatform handler (HttpBridge) replacing iisnode.web.configfor both sites,production.js/.envaligned (edfi_adminappleast-privilege login,API_PORTfromHTTP_PLATFORM_PORT,SSL_VERIFICATION).install-all.ps1example (SecureString passwords,-AppDbPassword) and a first sign-in note.Reference-doc alignment (EDFI-2779) — brought in line with the v4 scripts:
configuring-admin-app: fixed theENABLE_OPEN_APIkey, corrected DB encryption key length (64 hex chars), de-duplicated frontend build-time variables, fixed the OIDC config table name (oidc).git pull origin main.Database engine support per path (EDFI-2791):
DB_ENGINE=mssql+-MSSQL).Validation
markdownlintclean; Docusaurus build passes (no broken internal links).Related
Out of scope / follow-ups