Repository navigation
docs: move the deployment documentation into the repository - #2191
Merged
Merged
Conversation
The deployment guide lived in the wiki, which cannot be versioned, reviewed or kept in step with the code. It had drifted: of the 181 ovsx.* properties the server binds, 68 were undocumented - the whole ovsx.scanning.* family, ovsx.cors.public-origins, the access-token hashing settings, ovsx.migrations.* - while 15 documented properties no longer exist, among them everything under ovsx.publishing. and ovsx.elasticsearch.relevance.*, which was renamed to ovsx.search.relevance.* and is now documented under both names. In the repository a property can be documented in the same pull request that adds it, and scripts/config-properties-report.sh already lists every bound key, so a check that the two agree becomes possible. This move is deliberately content-preserving, so that reviewing the move is not tangled up with reviewing the corrections. Only three lines differ from the wiki text: four links into this repository are now repository-relative rather than absolute to eclipse/openvsx on master. Fixing the stale and missing properties comes next, separately. The NGINX page is folded in as the HTTPS Configuration section, since it is the other half of the same subject and was only ever reachable through a link at the bottom of the deployment page. The architectural overview stays in the wiki, along with its diagram, and gains a link here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The trim trailing whitespace pre-commit hook rejected the moved document. Most of it is padding in empty table cells; the three lines with two or more trailing spaces are each followed by a blank line, so none of them was a markdown hard line break and nothing renders differently. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Moves the deployment guide out of the wiki and into
doc/deployment.md, and folds the separate NGINXpage into it as the HTTPS section.
Why
The wiki cannot be versioned, reviewed, or updated in the same change as the code, and it has
drifted. Comparing the
ovsx.*properties the wiki documents against the ones the server actuallybinds in
src/main/java:The 66 include the entire
ovsx.scanning.*family - blocklist check, namespace-ownership check,secret detection with gitleaks - plus
ovsx.cors.public-origins, the access-token hashing settings(
token-hash-algorithm,-pepper,-previous-peppers,-accept-unpeppered) andovsx.migrations.*.The 15 are actively misleading: nothing under
ovsx.publishing.is bound any more(
require-license,unsupported-icon-formats), andovsx.elasticsearch.relevance.*was renamed toovsx.search.relevance.*but is still documented under both names. Alsoovsx.caching.extensionquery-*,ovsx.redis.embedded,ovsx.storage.cdn.*,ovsx.mirror.enabled.In the repository a property can be documented in the pull request that adds it, and
scripts/config-properties-report.shalready lists every bound key with its default, so a CI checkthat the guide and the code agree becomes possible. That check is the intended follow-up, and it
would have caught all 81 discrepancies above.
What is in this PR
Deliberately content-preserving, so that reviewing the move is not tangled up with reviewing the
corrections. Diffing the moved text against the wiki source gives exactly three changed lines, all
of them links into this repository that are now repository-relative instead of absolute to
eclipse/openvsxonmaster:.../blob/master/deploy/docker/build.sh../deploy/docker/build.sh.../blob/master/deploy/docker/configuration/application.yml../deploy/docker/configuration/application.yml.../blob/master/webui/src/default/theme.tsx../webui/src/default/theme.tsx.../blob/master/webui/src/page-settings.ts../webui/src/page-settings.tsEverything else is identical, stale entries included, apart from trailing whitespace: the wiki text
carried it on 36 lines and the
trim trailing whitespacehook rejects it. Most is padding in emptytable cells, and the three lines with two or more trailing spaces are each followed by a blank line,
so none was a markdown hard line break and nothing renders differently. The
#oauth2,#upstream-registryand#upstream-registry-instanceanchors were checked and still resolve within the new file.The NGINX page is folded in under
## HTTPS Configuration, its#### 1./#### 2.headings demotedto
###so they nest. It was only ever reachable through a link at the bottom of the deploymentpage, and it is the other half of the same subject.
README.mdgains a pointer to the new document under "Getting Started".What stays in the wiki
The architectural overview, along with its diagram, which lives in the wiki repository. Replacement
text for the two wiki pages is ready and should land once this merges, so that nothing points at a
file that is not yet on
main:moved are repointed at this document.
doc/deployment.md#https-configuration,keeping its title so existing inbound links still land somewhere useful.
Follow-ups
scripts/config-properties-report.shinto CI, so the guide cannot drift again.guidance. The NGINX example currently sets
proxy_set_header X-Forwarded-Host $host, and$hostis the client's
Hostheader, so the documented reference deployment forwards a client-controlledvalue - worth fixing along with the rest.
Prepared with Claude Code.