DR-005-Infra: Hosting Strategy for Module Documentation#
Hosting strategy for module webspaces
|
status: accepted
|
||||
Problem Description#
We currently host module documentation using GitHub Pages (per-repo webspaces).
GitHub Pages only allows 1GiB of webspace.
While this works so far, the storage and site limits are becoming noticeable.
The score platform repository currently has 1GiB in gh-pages (460MiB .git repo size).
More diagrams, pull-requests, and versions will exacerbate the problem.
Context#
In addition to GitHub Pages, the project also has the website https://eclipse.dev/score/ hosted via the Eclipse Foundation. The website is relatively small and there are plans to move most content elsewhere (where it can be managed via Wordpress).
The foundation updates the content every 5 minutes from the eclipse-score-website-published repo. The sources are in the eclipse-score-website repo and get deployed automatically using the GitHub Action Build and Archive.
No limits for this hosting are known.
Goals and Requirements#
Provide sufficient storage and bandwidth for documentation (releases and PR-previews).
Keep a consistent site/URL structure and navigation across modules.
Keep hosting and maintenance costs predictable and low.
Dedicated space for releases?
⚠️ What about additional documentation artifacts from DoxyGen, RustDoc, …?
Options Considered#
Option G: Continue with per-repo GitHub Pages (status quo)#
Keep publishing module webspaces to GitHub Pages. Invest efforts to keep space needs low as we only have 1GiB per repository. e.g. by optimizing page size, or providing PR previews only on demand.
😡 Effort: Increasing.
The effort is serious enough that we don’t consider the other criteria at all.
Option P: Publish Action into “published” Repo#
As we alread have the “eclipse-score-website-published” repository, we can push more content in there. Up to the 10GiB repo limit.
The limit is not 1GiB per repo anymore but 10GiB for all repos. That sounds worse at first, because with 20 repos, it would be 10GiB / 20. However, here the average size per repository matters. With option G above a single repo limit is already a problem. Still, this might not ease the problem sufficiently.
💚 Effort: We must adapt our GitHub action’s deploy steps.
😡 Speed: Updating a huge “published” repo will take time.
😡 Size: 10GiB total limit.
💚 Independence: No HelpDesk needed to potentially adapt configuration.
Option C: Combine Website from multiple Repos#
We let the eclipse.dev website pull content from multiple repositories. The configuration is done by the Eclipse Foundation:
Finally, to publish your website on eclipse.dev, you’ll need support from us to update your project’s website metadata in the projects.eclipse.org (PMI). This informs us on where to find the necessary static HTML to serve. You can request an update to your website deployment metadata by opening a ticket.
The configuration is visible as website_repo from
the Eclipse API of S-CORE.
💚 Effort: Request config change via Eclipse HelpDesk.
💚 Speed: Faster than option P because many small repos.
💚 Size: 10GiB per repo should suffice for a long time.
😡 Independence: HelpDesk needed to adapt configuration. (Add repo, rename folder)
Option D: Direct Webspace Push#
Instead of using the foundation’s pulling mechanism, we could push directly to some webspace from each module’s GitHub Action.
The eclipse.dev/score website is separate and not relevant for this option.
😡 Effort: Requires custom setup for the publication?
💚 Speed: Fast
💚 Size: Independent of any GitHub limits.
💚 Independence: Full control because custom.
Evaluation#
All options have the same costs in terms of hosting fees.
Criteria in order of importance (most important first):
Criteria |
Option G |
Option P |
Option C |
Option D |
|---|---|---|---|---|
Effort |
😡 |
💚 |
💚 |
❓ |
Size |
😡 |
😡 |
💚 |
💚 |
Speed |
❔ |
😡 |
💚 |
💚 |
Independence |
❔ |
💚 |
😡 |
💚 |
Option G is not sustainable due to increasing effort. Option P still has risky size limits. Thus we pick option E because deployment speed is more important than independence.
⚠️ evaluate option D properly