refactor: reorganize and rename documentation files for improved stru…

astro.config.mjs

@@ -4,6 +4,11 @@ import starlight from '@astrojs/starlight';
 import tailwindcss from '@tailwindcss/vite';
 import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi';
 
+export const locales = {
+	root: { label: 'English', lang: 'en' },
+	'zh-hant': { label: '繁體中文', lang: 'zh-Hant' }
+};
+
 // https://astro.build/config
 export default defineConfig({
 	site: 'https://otterscale.com',
@@ -21,34 +26,38 @@ export default defineConfig({
 				}
 			],
 			defaultLocale: 'root',
-			locales: {
-				root: {
-					label: 'English',
-					lang: 'en'
-				},
-				'zh-hant': {
-					label: '繁體中文',
-					lang: 'zh-Hant'
-				}
-			},
+			locales,
 			editLink: {
 				baseUrl: 'https://github.com/otterscale/otterscale.github.io/edit/main/docs/'
 			},
 			sidebar: [
 				{
-					label: 'Get Started',
-					slug: 'get-started'
+					label: 'Introduction',
+					slug: 'introduction',
+					translations: {
+						'zh-Hant': '簡介'
+					}
 				},
 				{
-					label: 'Scope',
-					slug: 'scope'
+					label: 'Getting Started',
+					translations: {
+						'zh-Hant': '開始使用'
+					},
+					autogenerate: { directory: 'getting-started' }
 				},
+
 				{
-					label: '基礎',
+					label: 'basic',
+					translations: {
+						'zh-Hant': '基本'
+					},
 					autogenerate: { directory: 'basic' }
 				},
 				{
-					label: '服務',
+					label: 'service',
+					translations: {
+						'zh-Hant': '服務'
+					},
 					autogenerate: { directory: 'service' }
 				},
 				...openAPISidebarGroups

src/content.config.ts

@@ -3,5 +3,5 @@ import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() })
 };

src/content/docs/getting-started/01-prerequisites.md

@@ -0,0 +1,61 @@
+---
+title: Prerequisites
+description: Hardware and network requirements for running OtterScale.
+---
+
+## System Requirements
+
+Before installing OtterScale, ensure your environment meets the following specifications.
+
+### Operating System
+
+| Component | Requirement                     |
+| :-------- | :------------------------------ |
+| **OS**    | **Ubuntu 24.04 LTS** (Required) |
+
+### Hardware Specifications
+
+| Resource       | Minimum Requirement      |
+| :------------- | :----------------------- |
+| **Memory**     | 8 GB RAM                 |
+| **Disk Space** | 100 GB available storage |
+
+### Network Configuration
+
+- **Connectivity:** At least one network interface with external internet access.
+- **Bridge Configuration:** The installation script checks for a network bridge named `br-otters`.
+  - _Existing:_ If found, it will be used automatically.
+  - _Missing:_ You will be prompted to select an existing bridge or create a new one.
+
+---
+
+## Firewall Configuration
+
+The installation process requires outbound access to various external services. Please whitelist the following domains and ports.
+
+### Core Infrastructure
+
+| Service Group           | Port(s)                            | Domains                                                                                                                                                                                                                                                      |
+| :---------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Canonical Services**  | TCP 443 (HTTPS)<br>TCP 80 (HTTP)\* | `api.charmhub.io`, `api.jujucharms.com`, `changelogs.ubuntu.com`, `charmhub.io`, `cloud-images.ubuntu.com`, `maas.ubuntu.com`, `images.maas.io`\*, `juju.is`, `jaas.ai`, `streams.canonical.com`, `objects.githubusercontent.com`, `contracts.canonical.com` |
+| **Snap Store**          | TCP 443                            | `snapcraft.io`, `api.snapcraft.io`, `storage.snapcraftcontent.com`, `*.cdn.snapcraftcontent.com`                                                                                                                                                             |
+| **Ubuntu Repos**        | TCP 443, 80                        | `archive.ubuntu.com`, `security.ubuntu.com`, `esm.ubuntu.com`, `ports.ubuntu.com`, `tw.archive.ubuntu.com`                                                                                                                                                   |
+| **GitHub & OtterScale** | TCP 443, 80                        | `otterscale.github.io`, `otterscale.com`, `github.com`, `raw.githubusercontent.com`                                                                                                                                                                          |
+
+### Container Registries & Images
+
+| Registry           | Port    | Domains                                                                                                                                   |
+| :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Kubernetes**     | TCP 443 | `registry.k8s.io`, `k8s.gcr.io`, `ghcr.io`, `storage.googleapis.com`, `d39mqg4b1dx9z1.cloudfront.net`                                     |
+| **Docker Hub**     | TCP 443 | `docker.io`, `hub.docker.com`, `auth.docker.io`, `registry-1.docker.io`, `production.cloudflare.docker.com`, `*.r2.cloudflarestorage.com` |
+| **NVIDIA**         | TCP 443 | `nvcr.io`                                                                                                                                 |
+| **Red Hat / Quay** | TCP 443 | `registry.redhat.io`, `quay.io`, `registry.access.redhat.com`                                                                             |
+| **Others**         | TCP 443 | `registry.cn-hangzhou.aliyuncs.com`                                                                                                       |
+
+### AI & Helm Resources
+
+| Category        | Port    | Domains                                                                                                                                                             |
+| :-------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **HuggingFace** | TCP 443 | `huggingface.co`, `cdn-lfs.huggingface.co`, `cdn.huggingface.co`                                                                                                    |
+| **Istio**       | TCP 443 | `istio.io`                                                                                                                                                          |
+| **Helm Charts** | TCP 443 | `charts.jetstack.io`, `charts.bitnami.com`, `open-feature.github.io`, `prometheus-community.github.io`, `project-hami.github.io`, `helm.ngc.nvidia.com`, `llm-d.ai` |

src/content/docs/getting-started/02-installation.md

@@ -0,0 +1,38 @@
+---
+title: Installation
+description: Step-by-step guide to installing OtterScale.
+---
+
+Follow the steps below to install and configure OtterScale.
+
+## Installation Process
+
+### 1. Start Services
+
+Run the following command to start the necessary services using Docker Compose:
+
+```bash
+docker-compose up -d
+```
+
+### 2. Configure Installation
+
+Create an `install.cfg` file with the required configuration. You can use the following template:
+
+```bash title="install.cfg"
+## MAAS DHCP Range IP
+MAAS_DHCP_START_IP="192.168.197.216"
+MAAS_DHCP_END_IP="192.168.197.219"
+
+## OtterScale Web IP
+OTTERSCALE_WEB_IP="192.168.197.220"
+```
+
+Ensure that the IP addresses are correctly configured for your network environment.
+
+### 3. Run Installation Script
+
+Execute the installation script through the User Interface:
+
+1.  Access the OtterScale UI.
+2.  Execute the `install.sh` script.

src/content/docs/getting-started/03-scope.md

@@ -0,0 +1,75 @@
+---
+title: Scope
+description: Manage scopes in OtterScale.
+---
+
+Scopes allow you to organize your resources and control access.
+
+## Selecting a Scope
+
+You can select a scope from the dropdown menu in the navigation bar. This will filter the resources you see to only those within the selected scope.
+
+## Creating a Scope
+
+To create a new scope, navigate to the Scope management area and click on "Create Scope". A side panel will appear with the creation form.
+
+### 1. Plan Selection
+
+At the top of the form, you will see the details of the plan associated with the scope you are creating. Different plans support different features:
+
+| Feature    | Standard    | Advanced   | Enterprise |
+| :--------- | :---------- | :--------- | :--------- |
+| Ceph       | ✅          | ✅         | ✅         |
+| Kubernetes | ✅          | ✅         | ✅         |
+| Cluster    | ❌          | ✅         | ✅         |
+| Node       | Single-Node | Multi-Node | Multi-Node |
+
+### 2. Scope Details
+
+Fill in the following information to configure your new scope:
+
+#### Scope Name
+
+- **Label**: Scope Name <span style="color: #eab308">●</span>
+- **Description**: Enter a unique name for your scope.
+- **Input**: Text field (Required).
+
+#### Machine Selection
+
+- **Label**: Machine <span style="color: #eab308">●</span>
+- **Description**: Select the physical machine to assign to this scope.
+- **Input**: Dropdown menu.
+  - The dropdown lists available machines that are in the `Ready` status.
+  - Hovering over the info icon <span class="iconify" data-icon="ph:info"></span> next to a machine name displays detailed hardware specifications (CPU, Memory, Storage, System info, etc.).
+
+#### Storage Devices
+
+- **Label**: Storage Devices <span style="color: #eab308">●</span>
+- **Description**: Select the block devices to be used by the scope.
+- **Input**: Checkboxes.
+  - This section appears after you select a machine.
+  - It lists available non-boot block devices.
+  - Hovering over a device shows its model and capacity.
+
+#### Network Configuration
+
+- **Calico CIDR** (Optional):
+  - **Description**: The CIDR block for Calico networking.
+  - **Input**: Text field (e.g., `192.168.0.0/16`).
+- **Virtual IP** (Optional):
+  - **Description**: The virtual IP address for the scope.
+  - **Input**: Text field (e.g., `192.168.1.1`).
+
+### 3. Creation Process
+
+Once you have filled in the details, click the **Create** button. The system will perform the following steps automatically:
+
+1.  **Create Scope**: Initializes the scope record.
+2.  **Add Machine Tags**: Tags the selected machine.
+3.  **Commission Machine**: Configures the machine (SSH, networking, storage).
+4.  **Wait for Ready**: Waits for the machine to report a `Ready` status.
+5.  **Create Machine**: Associates the machine with the scope.
+6.  **Wait for Agent**: Waits for the agent to start on the machine.
+7.  **Create Node**: Finalizes the node creation with network and storage settings.
+
+You will see a loading indicator and status messages during this process. Once complete, a success message will appear.

src/content/docs/index.mdx

@@ -18,7 +18,7 @@ hero:
     file: ../../assets/houston.webp
   actions:
     - text: Get Started
-      link: /guides/example/
+      link: /introduction/
       icon: right-arrow
     - text: View on Github
       link: https://github.com/otterscale/otterscale

src/content/docs/introduction.md

@@ -0,0 +1,38 @@
+---
+title: Get Started
+description: Get started with OtterScale.
+---
+
+OtterScale is a unified infrastructure management platform designed to simplify the deployment and operation of complex distributed systems. It integrates bare metal provisioning, container orchestration, and distributed storage into a single, cohesive interface.
+
+## System Architecture
+
+OtterScale is built on a layered architecture that provides complete control from the hardware up to the application layer.
+
+### Core Layers
+
+1.  **Hardware Layer**: Manages physical resources including Compute nodes, Storage nodes, and GPU accelerators.
+2.  **Provisioning Layer (MAAS)**: Handles bare metal provisioning, OS deployment, and network configuration.
+3.  **Orchestration Layer (Juju & Kubernetes)**: Manages application lifecycles and container orchestration.
+4.  **Storage Layer (Ceph)**: Provides scalable, distributed storage for the cluster.
+
+### Node Provisioning & Management
+
+OtterScale automates the lifecycle of physical nodes. Through the integration with MAAS, it handles power management (IPMI/Redfish), PXE booting, and OS installation.
+
+### Storage Topology
+
+The platform utilizes Ceph to provide a robust, self-healing storage fabric. Storage nodes are dedicated to managing data replication and distribution, ensuring high availability and performance for data-intensive workloads like AI model training.
+
+## Key Features
+
+- **Scope Management**: logically isolate resources and manage access control for different teams or projects.
+- **AI/LLM Readiness**: Optimized for high-performance computing with support for GPU acceleration and high-speed networking (InfiniBand/RoCE).
+- **Multi-Tenancy**: Securely share infrastructure across multiple users while maintaining resource isolation.
+- **Unified Interface**: A single pane of glass for monitoring and managing the entire stack, from metal to service.
+
+## Next Steps
+
+- [Check Prerequisites](/getting-started/01-prerequisites)
+- [Create a Scope](/getting-started/03-scope)
+- [Explore Basic Features](/basic/machines)