[DOCS-1442] Self-Managed deployment guide revamp#2113
[DOCS-1442] Self-Managed deployment guide revamp#2113mdlinville wants to merge 12 commits intomainfrom
Conversation
📚 Mintlify Preview Links✨ Added (8 total)📄 Pages (8)
📝 Changed (6 total)📄 Pages (5)
⚙️ Other (1)
🗑️ Deleted (6 total)View deleted files📄 Pages (6)
🤖 Generated automatically when Mintlify deployment succeeds |
🔗 Link Checker Results✅ All links are valid! No broken links were detected. Checked against: https://wb-21fd5541-operator-docs-revamp.mintlify.app |
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
c56b49d to
d2312a9
Compare
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
7fd62b6 to
cb18bb2
Compare
flamarion
left a comment
flamarion
left a comment
There was a problem hiding this comment.
I haven’t finished reviewing all the content yet, but assuming this was mostly a structural move (rather than content changes), everything looks reasonable so far.
One question I have is around the need to keep both:
Deploy W&B with Kubernetes OperatorDeploy on On-Premises Kubernetes
My suggestion would be to avoid centering this around on-prem and instead treat Kubernetes as a generic deployment method, independent of the environment.
Rationale
Kubernetes itself is fundamentally the same whether it runs on-prem or in the cloud — the core requirements and workflows don’t change. The main differences are usually in naming or managed services, for example:
- MySQL vs. RDS (AWS)
- S3 vs. another object storage
- Managed Redis vs. self-hosted Redis
Those are environment-specific details, but they don’t change the Kubernetes deployment model.
Suggested structure
You already do something similar with Deploy with Terraform on public cloud, which works well. Following that pattern, one option could be to group:
Deploy W&B with Kubernetes OperatorDeploy on Air-Gapped Kubernetes
under a broader section like:
Deploy on Kubernetes
or, if you prefer to keep the on-prem framing:
Deploy on On-Premises Kubernetes
This would reduce duplication, make the mental model clearer, and emphasize Kubernetes as the primary abstraction rather than the underlying environment.
I just pushed a commit that consolidates the Cloud and on-prem content into a single (main) Operator page, and left the airgapped content on a separate page since it's for a very particular sort of deployment and there is SEO merit here. I have maximized shared content between the main page and the airgapped page where possible, so updating a snippet will update both pages automatically. PTAL and let me know what you think. The redundant redirects the link checker is finding are expected for now. I need to fix the rest of them tomorrow. |
|
@mdlinville I was checking the branch deployment and wondered if this PR made it into this PR. |
mdlinville
force-pushed
the
operator_docs_revamp
branch
2 times, most recently
from
6d3e0f3 to
7b41f92
Compare
PTAL, I have made an attempt at further streamlining. This is not yet perfect copy wise, but it should give you an idea. |
- Create and edit snippets for shared object storage content
- Updates to BYOB page to clarify that it applies to all deployments
- Add a new Requirements page for Self-Managed
- Uses existing snippet imports extensively
- Clear cross-references to reference architecture
- Strong BYOB integration
- Sections:
- Software version requirements
- Hardware requirements
- Kubernetes (with OpenShift mention)
- MySQL database (with config parameters and creation instructions)
- Redis
- Object storage (with BYOB provisioning link and configuration transition)
- Networking (with DNS and load balancer info)
- SSL/TLS
- License
- Next steps (links to cloud, on-prem, airgapped guides)
- Create new directories for details specific to Cloud or on-premise
deployments, will be populated in phases 3 and 4s
- Update navigation
- Move and edit Operator landing page
- Update title
- Use shared BYOB content
- Adjust Before you begin
- Update links for file moves
- Adjust support storage provider list
- Improve cross-references
- Where possible, tabify content for Helm and Terraform to
simplify the giew
- Update navigation
- Create consolidated Terraform guide
- Shared intro, explanation of modules
- Adds a cloud provider selector
- Platform-specific content in tabs
- Prerequisites
- General steps
- Recommendations
- Specific details about Redis, message broker
- Links to more resources
- Update navigation
- Create connected and airgapped on-prem guides - Update requirements - Update navigation This resolves some links that were intentionally left broken after the last phase
Add redirects for files we moved, renamed, or consolidated Temporarily, redirect old Japanese / Korean destinations to English destinations
Delete old files we no longer need
Mintlify composes heading slugs algorithmically from the heading title, in both Markdown and HTML headings. There is no support for setting the heading slug manually, even by setting id on a HTML heading. This means that translated content will have different slugs than the English content, which will break anchor-level links in translated content. This script syncs deep links in translated content with the translated headings. A translator would run it toward the end of the translation refresh, perhaps just before creating the PR. - Full docs are in the README - Extracting and rewriting are handled separately - Supports dry-run and verbose modes - Supports operating on a specific translation or a specific file or all translations
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
9ad9f3a to
9a48de8
Compare
2 participants
Description
This PR completes a comprehensive restructure of the W&B self-managed deployment documentation to address confusion between deployment guides, consolidate shared requirements, improve discoverability, and incorporate enhanced OpenShift/air-gapped deployment guidance.
Key improvements:
The project was accomplished in 6 phases. Each phase is encapsulated into a commit for iterative review. See Changes by Phase.
Benefits
For Users
For Maintenance
For Support
Major Content Improvements
OpenShift Support
Air-Gapped Deployments
User Experience
Related Issues
Closes DOCS-1442
Changes by Phase
Reviewers: This project was completed in 6 phases, each in a separate commit. I suggest loading and scanning through each commit in sequence, before reviewing the HTML output using the Preview comment.
Phase 1: Foundation + Snippets
**Commit:** https://github.com//pull/2113/changes/6567f8668bb8028197611fd92c25279214dc3f8arequirements.mdxpage consolidating prerequisitesPhase 2: Operator Consolidation
**Commit:** https://github.com//pull/2113/changes/19785806b8a73d3ad60c0d3d5e940c17e54373d8operator.mdxtoself-managed/operator.mdxPhase 3: Cloud Terraform Consolidation
**Commit:** https://github.com//pull/2113/changes/90948936bf0ceebc823bd7e9842a9a06bc7a734faws-tf.mdx,gcp-tf.mdx,azure-tf.mdxinto singlecloud-deployments/terraform.mdxPhase 4: On-Premises Guides
**Commit:** https://github.com//pull/2113/changes/ae58ee25e23e7c92c98480c98ca148b131290d34on-premises-deployments/kubernetes.mdx(replaces bare-metal.mdx)on-premises-deployments/kubernetes-airgapped.mdxPhase 5: Redirects
**Commit:** https://github.com//pull/2113/changes/559d904cfda61f22d0442cf2ff491907120853e1Phase 6: Cleanup
**Commit:** https://github.com//pull/2113/changes/d2312a94f3cf2cb40b0d001c5ac8cda254aa7a2bPhase 7: Address feedback
- Consolidated Cloud and on-prem guides into a single page - Left airgapped guide as a separate page - Maximized content reuse and single-sourcing between the twoNew Documentation Structure
Files Removed
- platform/hosting/operator.mdx (moved) - platform/hosting/self-managed/bare-metal.mdx (replaced) - platform/hosting/self-managed/operator-airgapped.mdx (replaced) - platform/hosting/self-managed/aws-tf.mdx (consolidated) - platform/hosting/self-managed/gcp-tf.mdx (consolidated) - platform/hosting/self-managed/azure-tf.mdx (consolidated)Redirects Added
All old URLs redirect to new locations:
English:
/platform/hosting/operator→/platform/hosting/self-managed/operator/platform/hosting/self-managed/bare-metal→/platform/hosting/self-managed/on-premises-deployments/kubernetes/platform/hosting/self-managed/operator-airgapped→/platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped/platform/hosting/self-managed/aws-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/gcp-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/azure-tf→/platform/hosting/self-managed/cloud-deployments/terraformLocalized (ja/ and ko/):
Testing Checklist
mint dev,mint validatecat docs.json | python3 -m json.toolFollowup tasks for localization team
Japanese and Korean localized files still exist but redirect to English versions. The localization team should:
Translate new/updated content (5 files):
platform/hosting/self-managed/requirements.mdx(NEW)platform/hosting/self-managed/operator.mdx(enhanced)platform/hosting/self-managed/cloud-deployments/terraform.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped.mdx(NEW)Delete old localized files (6 per language):
ja/platform/hosting/operator.mdxandko/platform/hosting/operator.mdx{ja,ko}/platform/hosting/self-managed/bare-metal.mdx{ja,ko}/platform/hosting/self-managed/operator-airgapped.mdx{ja,ko}/platform/hosting/self-managed/{aws,gcp,azure}-tf.mdxUpdate navigation in
docs.jsonfor ja/ and ko/ sectionsTimeline: No urgency - redirects serve English content until translations ready.
Statistics