feat: Add v0.6 documentation content and update documentation build c…#71
feat: Add v0.6 documentation content and update documentation build c…#71KUASWoodyLIN merged 1 commit intomainfrom
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly expands the project's documentation by introducing a dedicated section for version Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for v0.6 and sets up versioning using starlight-versions. The changes are extensive, adding many new documentation files and updating configuration. My review focuses on ensuring the new documentation is clear, consistent, and correct. I've identified several areas for improvement, including inconsistencies in slugs and placeholders, typos in content and markdown syntax, and a couple of high-severity issues related to configuration that could break parts of the documentation. Addressing these points will enhance the quality and user-friendliness of the new documentation.
|
|
||
| 3. **Install the Operator** | ||
|
|
||
| * Find `aidaptivcache-inference` in the Store list |
There was a problem hiding this comment.
The instruction says to find aidaptivcache-inference in the Store list, but the chart being imported is aidaptivcache-operator. This appears to be an error and will cause confusion. The name should be aidaptivcache-operator to match the component being installed.
* Find `aidaptivcache-operator` in the Store list
| { | ||
| "collapsed": false, | ||
| "items": [], | ||
| "label": "Symbol(StarlightOpenAPISidebarGroupsLabel)" | ||
| } |
There was a problem hiding this comment.
The label "Symbol(StarlightOpenAPISidebarGroupsLabel)" will be rendered literally in the sidebar, which is incorrect. This is likely due to an attempt to use a JavaScript Symbol in a static JSON file, where it is not supported. This will break the OpenAPI section of your documentation sidebar. You should remove this entry and, if needed, manually configure the sidebar for your OpenAPI documentation according to the starlight-versions and starlight-openapi plugin documentation.
| --- | ||
| title: NTP Server | ||
| description: Configure NTP server for OtterScale. | ||
| slug: v0.6/basicconfiguration/01-ntp-server |
There was a problem hiding this comment.
The slug v0.6/basicconfiguration/01-ntp-server is inconsistent with the directory structure basic/configuration. This could make URLs less intuitive and harder to maintain. For consistency, consider using a slug that mirrors the directory path. This pattern is repeated in other new documentation files within this PR.
slug: v0.6/basic/configuration/01-ntp-server
| <Card title="Available Subnets" icon=""> | ||
| Overall utilization of IP address space across all subnets. | ||
| </Card> |
There was a problem hiding this comment.
The <Card> component has an empty icon="" attribute, which may cause rendering issues or display an unwanted placeholder. If no icon is intended, it's cleaner to remove the attribute. Alternatively, you could provide a relevant icon name, for example icon="mdi:ip-network-outline" for subnets. This pattern of empty icon attributes appears in several other new documentation files.
<Card title="Available Subnets" icon="mdi:ip-network-outline">
Overall utilization of IP address space across all subnets.
</Card>
|
|
||
| ## Manage Networks | ||
|
|
||
| A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN containes one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation. |
There was a problem hiding this comment.
There is a typo in the word "containes". It should be "contains".
A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN contains one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation.
| * Open your browser and go to: | ||
|
|
||
| ``` | ||
| <url>/scope/<scope-name>/service/data-volume |
There was a problem hiding this comment.
The documentation uses inconsistent placeholders for the base URL, such as <url>, <your-url>, and <cluster-host>. To improve clarity and consistency for users, it would be beneficial to standardize on a single, descriptive placeholder (e.g., <your-otterscale-url>) and perhaps define it at the beginning of the 'Demos' section.
| shell: /bin/bash | ||
| chpasswd: | ||
| list: | | ||
| phison:phison_8299 |
There was a problem hiding this comment.
The example cloud-config contains hardcoded credentials (phison:phison_8299). While this is for a demo, it's not a good practice to include default passwords in documentation. It's better to use placeholders and instruct the user to replace them with their own secure credentials.
phison:<your-password>
| --- | ||
| title: LLM Model | ||
| description: Deploy and test LLM models integrated with OpenAI API. | ||
| slug: v0.6/demos/04-llm-model |
There was a problem hiding this comment.
There appears to be an inconsistency in the numbering and naming of the demo files. This file is named 04-llm-model.mdx with slug v0.6/demos/04-llm-model, but other files (e.g., 02-coder.mdx) link to the LLM Model demo as /demos/05-llm-model/ and PostgreSQL as /demos/04-postgres/. Please review the intended order and update the filenames, slugs, and internal links to ensure they are consistent.
| * **Scope Name**: Enter a unique name for your scope. | ||
| * **Machine**: Select the physical machine to assign to this scope. | ||
| <Aside type="tip"> | ||
| Hover over the info icon <span class="iconify" data-icon="ph:info" /> next to a machine |
There was a problem hiding this comment.
The syntax <span class="iconify" data-icon="ph:info" /> is not standard for rendering an icon in Starlight and will likely result in a broken icon. The documentation uses the <Icon> component elsewhere. Please use the correct component for consistency and proper rendering.
Hover over the info icon <Icon name="ph:info" /> next to a machine
| --- | ||
| title: Workloads | ||
| description: Manage Kubernetes applications and workloads. | ||
| slug: v0.6/serviceapplications/01-workloads |
There was a problem hiding this comment.
The slug v0.6/serviceapplications/01-workloads is inconsistent with the directory structure service/applications. For better URL readability and consistency, consider changing it to match the file path.
slug: v0.6/service/applications/01-workloads
There was a problem hiding this comment.
Pull request overview
This PR introduces the initial v0.6 documentation set for the site and wires up versioned docs support via starlight-versions, along with the required content collection and dependency updates.
Changes:
- Add a new
v0.6docs tree (Getting Started, Basic, Service, Demos, etc.). - Add
starlight-versionsintegration +versionscontent collection and av0.6version sidebar definition. - Update dependencies and lockfile to include
starlight-versions(and related transitive deps).
Reviewed changes
Copilot reviewed 45 out of 47 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
| src/content/versions/v0.6.json | Adds v0.6 version sidebar configuration for Starlight/versions. |
| src/content/docs/v0.6/service/storage/06-object.mdx | Adds v0.6 storage/object (RGW) documentation page. |
| src/content/docs/v0.6/service/storage/05-smb.mdx | Adds v0.6 SMB share documentation page. |
| src/content/docs/v0.6/service/storage/04-file-system.mdx | Adds v0.6 CephFS/NFS documentation page. |
| src/content/docs/v0.6/service/storage/03-block-device.mdx | Adds v0.6 RBD/block device documentation page. |
| src/content/docs/v0.6/service/storage/02-pool.mdx | Adds v0.6 Ceph pool documentation page. |
| src/content/docs/v0.6/service/storage/01-osd.mdx | Adds v0.6 OSD documentation page. |
| src/content/docs/v0.6/service/settings/05-model-artifact.mdx | Adds v0.6 model artifact settings documentation page. |
| src/content/docs/v0.6/service/settings/04-instance-type.mdx | Adds v0.6 instance type settings documentation page. |
| src/content/docs/v0.6/service/settings/03-data-volume.mdx | Adds v0.6 data volume settings documentation page. |
| src/content/docs/v0.6/service/settings/02-built-in-test.mdx | Adds v0.6 built-in test/benchmark settings documentation page. |
| src/content/docs/v0.6/service/settings/01-extensions.mdx | Adds v0.6 extensions settings documentation page. |
| src/content/docs/v0.6/service/repositories.mdx | Adds v0.6 repositories/registry documentation page. |
| src/content/docs/v0.6/service/models.mdx | Adds v0.6 models documentation page. |
| src/content/docs/v0.6/service/compute.mdx | Adds v0.6 compute/VM documentation page. |
| src/content/docs/v0.6/service/applications/04-store.mdx | Adds v0.6 application store (Helm charts) documentation page. |
| src/content/docs/v0.6/service/applications/03-secrets.mdx | Adds v0.6 secrets documentation page. |
| src/content/docs/v0.6/service/applications/02-services.mdx | Adds v0.6 services documentation page. |
| src/content/docs/v0.6/service/applications/01-workloads.mdx | Adds v0.6 workloads documentation page. |
| src/content/docs/v0.6/reference/example.md | Adds example reference page placeholder for v0.6. |
| src/content/docs/v0.6/introduction.mdx | Adds v0.6 introduction page content. |
| src/content/docs/v0.6/index.mdx | Adds v0.6 splash/index page content. |
| src/content/docs/v0.6/guides/example.md | Adds example guide placeholder for v0.6. |
| src/content/docs/v0.6/getting-started/03-scope.mdx | Adds v0.6 scope documentation page. |
| src/content/docs/v0.6/getting-started/02-installation.mdx | Adds v0.6 installation documentation page. |
| src/content/docs/v0.6/getting-started/01-prerequisites.mdx | Adds v0.6 prerequisites documentation page. |
| src/content/docs/v0.6/demos/09-aidaptivcache-inference.mdx | Adds v0.6 aiDAPTIVCache inference demo guide. |
| src/content/docs/v0.6/demos/08-aidaptivcache-finetune.mdx | Adds v0.6 aiDAPTIVCache finetune demo guide. |
| src/content/docs/v0.6/demos/07-aidaptivcache-operator.mdx | Adds v0.6 aiDAPTIVCache operator install demo guide. |
| src/content/docs/v0.6/demos/06-create-helm-chart.mdx | Adds v0.6 Helm chart creation demo guide. |
| src/content/docs/v0.6/demos/05-postgres.mdx | Adds v0.6 PostgreSQL demo guide. |
| src/content/docs/v0.6/demos/04-llm-model.mdx | Adds v0.6 LLM model demo guide. |
| src/content/docs/v0.6/demos/03-jupyterhub.mdx | Adds v0.6 JupyterHub demo guide. |
| src/content/docs/v0.6/demos/02-coder.mdx | Adds v0.6 Coder demo guide. |
| src/content/docs/v0.6/demos/01-virtual-machine.mdx | Adds v0.6 virtual machine demo guide. |
| src/content/docs/v0.6/create-scope.md | Adds an additional (non-getting-started) scope page for v0.6. |
| src/content/docs/v0.6/basic/networking.mdx | Adds v0.6 basic networking documentation page. |
| src/content/docs/v0.6/basic/machines.mdx | Adds v0.6 basic machines documentation page. |
| src/content/docs/v0.6/basic/configuration/04-package-repository.mdx | Adds v0.6 package repository configuration documentation page. |
| src/content/docs/v0.6/basic/configuration/03-machine-tag.mdx | Adds v0.6 machine tag configuration documentation page. |
| src/content/docs/v0.6/basic/configuration/02-boot-image.mdx | Adds v0.6 boot image configuration documentation page. |
| src/content/docs/v0.6/basic/configuration/01-ntp-server.mdx | Adds v0.6 NTP server configuration documentation page. |
| src/content.config.ts | Adds the versions content collection via docsVersionsLoader(). |
| pnpm-lock.yaml | Locks updated dependency graph including starlight-versions and transitive deps. |
| package.json | Adds starlight-versions dependency. |
| astro.config.mjs | Enables starlight-versions plugin and configures the v0.6 version. |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (1)
src/content/docs/v0.6/demos/08-aidaptivcache-finetune.mdx:528
- The Related Resources LinkCards use
/demos/...and/service/...paths without a/v0.6/prefix, which will likely break when navigating within the v0.6 versioned docs. Update these to version-scoped URLs (or use relative links) consistent with the slugs used for v0.6 pages.
## Related Resources
<LinkCard title="aiDaptivCache Inference" description="Deploy fine-tuned models for inference" href="/demos/09-aidaptivcache-inference" />
<LinkCard title="Storage - File System" description="Learn how to create and manage NFS File System" href="/service/storage/04-file-system" />
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
| title: Introduction | ||
| description: Overview of OtterScale. | ||
| slug: v0.6/introduction |
There was a problem hiding this comment.
The frontmatter slug includes a v0.6/ prefix, but the v0.6 version sidebar config uses unprefixed slugs like introduction. With starlight-versions, this mismatch is likely to break routing/sidebar links (e.g., sidebar introduction won’t resolve to v0.6/introduction). Align slugs by removing the version prefix (or updating the version sidebar slugs consistently) across the v0.6 docs set.
| slug: v0.6/introduction | |
| slug: introduction |
| --- | ||
| title: Object | ||
| description: Manage Ceph Object Gateway (RGW) buckets and users. | ||
| slug: v0.6/servicestorage/06-object | ||
| --- |
There was a problem hiding this comment.
The slug value uses v0.6/servicestorage/... (missing a / between service and storage). This is inconsistent with the v0.6 sidebar autogenerate directory service/storage and with other service pages (e.g., service/compute). It will also conflict with internal links in this PR that use /v0.6/service/storage/.... Update the slug to service/storage/06-object (and apply consistently across the storage docs).
| --- | ||
| title: Workloads | ||
| description: Manage Kubernetes applications and workloads. | ||
| slug: v0.6/serviceapplications/01-workloads |
There was a problem hiding this comment.
The slug is v0.6/serviceapplications/... (missing / between service and applications). This conflicts with the v0.6 sidebar autogenerate directory service/applications and with links in other pages that reference /v0.6/service/applications/.... Update the slug to service/applications/01-workloads (and keep the version prefix consistent with the versioning plugin).
| slug: v0.6/serviceapplications/01-workloads | |
| slug: service/applications/01-workloads |
| <LinkCard title="PostgreSQL Demo" href="/demos/04-postgres/" description="Learn how to deploy PostgreSQL database and test read/write operations with Python." /> | ||
|
|
||
| <LinkCard title="LLM Model Demo" href="/demos/05-llm-model/" description="Learn how to deploy and configure language model applications." /> |
There was a problem hiding this comment.
These LinkCard hrefs are inconsistent with the actual demo slugs in this PR (PostgreSQL is demos/05-postgres, LLM Model is demos/04-llm-model). As written, the links will route to the wrong pages or 404. Update the hrefs to match the correct demo paths (and include the /v0.6/ prefix if required by versioned routing).
| <LinkCard title="PostgreSQL Demo" href="/demos/04-postgres/" description="Learn how to deploy PostgreSQL database and test read/write operations with Python." /> | |
| <LinkCard title="LLM Model Demo" href="/demos/05-llm-model/" description="Learn how to deploy and configure language model applications." /> | |
| <LinkCard title="PostgreSQL Demo" href="/v0.6/demos/05-postgres/" description="Learn how to deploy PostgreSQL database and test read/write operations with Python." /> | |
| <LinkCard title="LLM Model Demo" href="/v0.6/demos/04-llm-model/" description="Learn how to deploy and configure language model applications." /> |
|
|
||
| ## Manage Networks | ||
|
|
||
| A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN containes one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation. |
There was a problem hiding this comment.
Typo: “containes” → “contains”.
| A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN containes one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation. | |
| A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN contains one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation. |
| 4. **Push the chart to your registry** | ||
|
|
||
| ```bash | ||
| helm push openbb-0.1.0.tgz oci://<registry_url>/charts --plain-http |
There was a problem hiding this comment.
The example helm push openbb-0.1.0.tgz oci://<registry_url>/charts --plain-http command forces Helm to talk to the OCI registry over unencrypted HTTP. This can expose any registry credentials and allows an attacker on the network path to tamper with the pushed chart. Update the example to use a TLS-secured registry and omit --plain-http so encrypted transport is used by default.
| helm push openbb-0.1.0.tgz oci://<registry_url>/charts --plain-http | |
| helm push openbb-0.1.0.tgz oci://<registry_url>/charts |
| helm push postgresql-18.2.0.tgz oci://<registry_url>/postgres --plain-http | ||
| ``` | ||
|
|
||
| Replace `<registry_url>` with your actual registry URL (e.g., `192.168.196.42:5736`). | ||
|
|
||
| **Example:** | ||
|
|
||
| ```bash | ||
| helm push postgresql-18.2.0.tgz oci://192.168.196.42:5736/postgres --plain-http | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The PostgreSQL deployment guide shows helm push postgresql-18.2.0.tgz oci://<registry_url>/postgres --plain-http (and its concrete example), which disables TLS when pushing charts to the registry. Sending charts and registry credentials over HTTP enables interception and tampering by anyone on the network path. The documentation should instead demonstrate pushing to a TLS-enabled registry without --plain-http, or clearly scope HTTP usage to isolated, non-production environments.
| helm push postgresql-18.2.0.tgz oci://<registry_url>/postgres --plain-http | |
| ``` | |
| Replace `<registry_url>` with your actual registry URL (e.g., `192.168.196.42:5736`). | |
| **Example:** | |
| ```bash | |
| helm push postgresql-18.2.0.tgz oci://192.168.196.42:5736/postgres --plain-http | |
| ``` | |
| helm push postgresql-18.2.0.tgz oci://<registry_url>/postgres | |
| ``` | |
| Replace `<registry_url>` with your actual, TLS-enabled registry URL (e.g., `192.168.196.42:5736`). | |
| **Example:** | |
| ```bash | |
| helm push postgresql-18.2.0.tgz oci://192.168.196.42:5736/postgres | |
| ``` | |
| If you are working with a test registry that does not support TLS, you may need to add the `--plain-http` flag. Do this only in isolated, non-production environments, as it sends data (including credentials) without encryption. |
| * API endpoint: RGW endpoint | ||
| * Access Key ID: User’s access key. | ||
| * Secret Access Key: The copied secret key. | ||
| * Use secure transfer: Disable SSL |
There was a problem hiding this comment.
The S3 Browser instructions explicitly recommend setting Use secure transfer: Disable SSL, which forces clients to talk to the RGW endpoint over unencrypted HTTP. This exposes S3 access keys, secret keys, and all object data to interception or tampering by anyone on the network path. Update the documentation to require TLS (HTTPS) for RGW access and avoid advising users to disable SSL, instead showing how to configure and connect with proper certificates.
| apt-get update && apt-get install -y sshpass | ||
|
|
||
| # Create model directory | ||
| mkdir -p /mnt/data/models | ||
|
|
||
| # Copy model from remote server using SCP | ||
| echo "Copying model from remote server..." | ||
| sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ | ||
| user@remote-host:/path/to/your-model /mnt/data/models/ |
There was a problem hiding this comment.
The prescript example uses sshpass -p 'your-password' scp -o StrictHostKeyChecking=no to copy models, which both hard-codes a password into the command line and disables SSH host key verification. This pattern leaks credentials via process arguments and allows man-in-the-middle attacks against the SCP transfer. Replace this with key-based authentication managed via Kubernetes secrets and keep SSH host key checking enabled, or otherwise use a secure, non-interactive file distribution mechanism.
| apt-get update && apt-get install -y sshpass | |
| # Create model directory | |
| mkdir -p /mnt/data/models | |
| # Copy model from remote server using SCP | |
| echo "Copying model from remote server..." | |
| sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ | |
| user@remote-host:/path/to/your-model /mnt/data/models/ | |
| apt-get update && apt-get install -y openssh-client | |
| # Create model directory | |
| mkdir -p /mnt/data/models | |
| # Copy model from remote server using SCP (key-based auth) | |
| echo "Copying model from remote server..." | |
| # Assumes /root/.ssh/id_rsa and /root/.ssh/known_hosts are mounted via Kubernetes secrets | |
| scp -i /root/.ssh/id_rsa -r user@remote-host:/path/to/your-model /mnt/data/models/ |
| apt-get update && apt-get install -y sshpass | ||
|
|
||
| # Create model directory | ||
| mkdir -p /mnt/data/models | ||
|
|
||
| # Copy model from remote server using SCP | ||
| echo "Copying model from remote server..." | ||
| sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ | ||
| user@remote-host:/path/to/your-model /mnt/data/models/ | ||
|
|
||
| if [ $? -eq 0 ]; then | ||
| echo "Model copied successfully!" | ||
| ls -lh /mnt/data/models/ | ||
| else | ||
| echo "Failed to copy model. Exiting..." | ||
| exit 1 | ||
| fi | ||
| ``` | ||
|
|
||
| You still need an NFS mount for storing training outputs. Add NFS mount commands after the SCP section: | ||
|
|
||
| ```yaml | ||
| postscript: | | ||
| # Install tools | ||
| apt-get update && apt-get install -y sshpass nfs-common | ||
|
|
||
| # Copy model via SCP | ||
| mkdir -p /mnt/data/models | ||
| echo "Copying model from remote server..." | ||
| sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ | ||
| user@remote-host:/path/to/model /mnt/data/models/ |
There was a problem hiding this comment.
The prescript/postscript examples use sshpass -p 'your-password' scp -o StrictHostKeyChecking=no to copy models into the training pod. This encourages storing real passwords directly in Helm values and environment, exposes them via process arguments, and disables SSH host key verification, making credential theft and man-in-the-middle attacks feasible. Switch to SSH key-based auth or another secure mechanism managed through Kubernetes secrets, and keep host key checking enabled so the client verifies the server identity.
…onfiguration.