Skip to content

docs: move the deployment documentation into the repository - #2191

Merged
netomi merged 2 commits into
mainfrom
docs/deployment-guide
Sep 10, 2026
Merged

netomi merged 2 commits into
mainfrom
docs/deployment-guide

Conversation

@netomi

@netomi netomi commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Moves the deployment guide out of the wiki and into doc/deployment.md, and folds the separate NGINX
page 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 actually
binds in src/main/java:

count
properties bound in the code 179
documented in the wiki 132
bound but undocumented 66
documented but no longer in the code 15

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) and
ovsx.migrations.*.

The 15 are actively misleading: nothing under ovsx.publishing. is bound any more
(require-license, unsupported-icon-formats), and ovsx.elasticsearch.relevance.* was renamed to
ovsx.search.relevance.* but is still documented under both names. Also
ovsx.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.sh already lists every bound key with its default, so a CI check
that 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/openvsx on master:

was now
.../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.ts

Everything else is identical, stale entries included, apart from trailing whitespace: the wiki text
carried it on 36 lines and the trim trailing whitespace hook rejects it. Most is padding in empty
table 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-registry and
#upstream-registry-instance anchors were checked and still resolve within the new file.

The NGINX page is folded in under ## HTTPS Configuration, its #### 1./#### 2. headings demoted
to ### so they nest. It was only ever reachable through a link at the bottom of the deployment
page, and it is the other half of the same subject.

README.md gains 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:

  • Deploying Open VSX keeps the overview and links here; its two in-page links to sections that
    moved are repointed at this document.
  • NGINX HTTPS Configuration becomes a short pointer to doc/deployment.md#https-configuration,
    keeping its title so existing inbound links still land somewhere useful.

Follow-ups

  1. Wire scripts/config-properties-report.sh into CI, so the guide cannot drift again.
  2. Correct the content: the 15 stale entries, the 66 missing properties, and the reverse-proxy
    guidance. The NGINX example currently sets proxy_set_header X-Forwarded-Host $host, and $host
    is the client's Host header, so the documented reference deployment forwards a client-controlled
    value - worth fixing along with the rest.

Prepared with Claude Code.

netomi and others added 2 commits September 10, 2026 08:45
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant