Refactor documentation 1

astro.config.mjs

@@ -18,6 +18,7 @@ export default defineConfig({
 			logo: {
 				src: './src/assets/logo.png'
 			},
+			favicon: '/logo.png',
 			social: [
 				{
 					icon: 'github',
@@ -47,14 +48,14 @@ export default defineConfig({
 				},
 
 				{
-					label: 'basic',
+					label: 'Basic',
 					translations: {
 						'zh-Hant': '基本'
 					},
 					autogenerate: { directory: 'basic' }
 				},
 				{
-					label: 'service',
+					label: 'Service',
 					translations: {
 						'zh-Hant': '服務'
 					},

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

@@ -3,6 +3,8 @@ title: Prerequisites
 description: Hardware and network requirements for running OtterScale.
 ---
 
+import { Card, CardGrid, Aside, Tabs, TabItem, Badge } from '@astrojs/starlight/components';
+
 ## System Requirements
 
 Before installing OtterScale, ensure your environment meets the following specifications.
@@ -13,7 +15,7 @@ Before installing OtterScale, ensure your environment meets the following specif
 | :-------- | :------------------------------ |
 | **OS**    | **Ubuntu 24.04 LTS** (Required) |
 
-### Hardware Specifications
+### Hardware
 
 | Resource       | Minimum Requirement      |
 | :------------- | :----------------------- |
@@ -33,16 +35,18 @@ Before installing OtterScale, ensure your environment meets the following specif
 
 The installation process requires outbound access to various external services. Please whitelist the following domains and ports.
 
-### Core Infrastructure
+<Tabs>
+  <TabItem label="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`                                                                                                                                                                          |
+| 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
+  </TabItem>
+  <TabItem label="Registries & Images">
 
 | Registry           | Port    | Domains                                                                                                                                   |
 | :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -52,10 +56,14 @@ The installation process requires outbound access to various external services.
 | **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
+  </TabItem>
+  <TabItem label="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` |
+
+  </TabItem>
+</Tabs>

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

@@ -0,0 +1,45 @@
+---
+title: Installation
+description: Step-by-step guide to installing OtterScale.
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+Follow the steps below to install and configure OtterScale.
+
+<Steps>
+
+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"
+    ```
+
+    <Aside type="caution" title="Network Configuration">
+    	Ensure that the IP addresses are correctly configured for your network environment. Incorrect
+    	settings may cause connectivity issues.
+    </Aside>
+
+3.  **Run Installation Script**
+
+    Execute the installation script through the User Interface:
+
+    1.  Access the OtterScale UI.
+    2.  Execute the `install.sh` script.
+
+</Steps>

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

@@ -0,0 +1,127 @@
+---
+title: Scope
+description: Manage scopes in OtterScale.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
+import { Icon } from '@astrojs/starlight/components';
+
+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.
+
+<Steps>
+
+1.  **Select a Plan**
+
+    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       | <Icon name="approve-check" /> | <Icon name="approve-check" /> | <Icon name="approve-check" /> |
+    | Kubernetes | <Icon name="approve-check" /> | <Icon name="approve-check" /> | <Icon name="approve-check" /> |
+    | Cluster    | <Icon name="close" />         | <Icon name="approve-check" /> | <Icon name="approve-check" /> |
+    | Node       | Single-Node                   | Multi-Node                    | Multi-Node                    |
+
+2.  **Configure Scope Details**
+
+    Fill in the following information to configure your new scope:
+
+    - **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"></span> next to a machine
+      	name to view detailed hardware specifications.
+      </Aside>
+    - **Storage Devices**: Select the block devices to be used. (Appears after selecting a machine).
+      <Aside type="tip">Hover over a device to see its model and capacity.</Aside>
+    - **Network Configuration** (Optional):
+      - **Calico CIDR**: The CIDR block for Calico networking (e.g., `192.168.0.0/16`).
+      - **Virtual IP**: The virtual IP address for the scope (e.g., `192.168.1.1`).
+
+3.  **Create Scope**
+
+    Once you have filled in the details, click the **Create** button to initiate the creation process.
+
+</Steps>
+
+## Automated Provisioning
+
+After you initiate the creation, the system automatically performs the following steps:
+
+<Steps>
+
+1.  **Create Scope**: Initializes the scope record.
+
+    This step maps to the Juju `CreateModel` operation. It establishes a new isolated workspace (Model) within the Juju controller. Key actions include:
+
+    - **Namespace Isolation**: Creates a logical boundary for resources, ensuring that applications and machines in this scope do not interfere with others.
+    - **Environment Configuration**: Sets up model-level configurations, such as APT mirrors for faster package downloads.
+    - **Access Control**: Automatically injects SSH keys to grant authorized users access to the machines within this scope.
+
+2.  **Add Machine Tags**: Tags the selected machine.
+
+    This step applies specific tags to the machine in MAAS. Tags are used to:
+
+    - **Mark Ownership**: Associates the machine with the specific scope being created.
+    - **Reserve Resources**: Prevents other processes from accidentally using this machine while it is being set up.
+    - **Define Capabilities**: Can be used to indicate specific hardware capabilities or roles (e.g., `compute`, `storage`) required for the node.
+
+3.  **Commission Machine**: Configures the machine (SSH, networking, storage).
+
+    Commissioning is a critical step to verify hardware and prepare it for deployment. It involves:
+
+    - **Hardware Inventory**: Boots an ephemeral OS to scan and record detailed specs (CPU, Memory, Disks, NICs).
+    - **Health Checks**: Runs scripts to test hardware functionality (Disk I/O, Memory, IPMI/BMC).
+    - **Configuration**: Sets up out-of-band management (BMC/IPMI) and registers network/storage interfaces.
+    - **Status Change**: On success, the machine becomes `Ready` for deployment. On failure, it is marked as `Failed commissioning` for troubleshooting.
+
+4.  **Wait for Ready**: Waits for the machine to report a `Ready` status.
+
+    The `Ready` status is mandatory before any further actions can be taken. It confirms that:
+
+    - Commissioning has completed successfully.
+    - The machine is free and available in the pool.
+    - It is eligible to be allocated and deployed with an operating system.
+      Attempting to deploy a machine that is not `Ready` (e.g., still commissioning or in a broken state) will fail.
+
+5.  **Create Machine**: Associates the machine with the scope.
+
+    This step executes the Juju `AddMachines` operation. It registers the specific physical machine (from MAAS) into the Juju controller. This action triggers:
+
+    - **Provisioning**: Juju instructs MAAS to deploy the operating system (e.g., Ubuntu) onto the machine.
+    - **Agent Installation**: Once the OS is running, the Juju Agent is installed, allowing Juju to manage the machine as a node.
+
+6.  **Wait for Agent**: Waits for the agent to start on the machine.
+
+    This step monitors the Juju Agent status until it reports as `started`. This signifies that:
+
+    - The OS installation is complete and the machine has booted.
+    - The Juju Agent is running and has successfully connected to the Juju Controller.
+    - The node is now online and ready to accept software deployments (Charms).
+
+7.  **Create Node**: Finalizes the node creation with network and storage settings.
+
+    This is the final orchestration step where the actual software stack is deployed. It performs the following actions:
+
+    - **Network Reservation**: Reserves necessary IP addresses for internal services (e.g., Ceph NFS, Kubernetes Load Balancer).
+    - **Software Deployment**: Deploys and configures the core components:
+      - **Ceph**: For distributed storage (using the selected OSD devices).
+      - **Kubernetes**: For container orchestration (configuring Calico networking and Load Balancers).
+      - **Addons**: Additional system utilities.
+      - **Observability (COS)**: Monitoring and logging stack.
+    - **Relation Establishment**: Connects these components together to ensure they work as a cohesive system.
+
+</Steps>
+
+<Aside type="note">
+	You will see a loading indicator and status messages during this process. Once complete, a success
+	message will appear.
+</Aside>