diff --git a/astro.config.mjs b/astro.config.mjs index deb45a8..373716a 100644 --- a/astro.config.mjs +++ b/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 diff --git a/src/content.config.ts b/src/content.config.ts index d9ee8c9..50cb18c 100644 --- a/src/content.config.ts +++ b/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() }) }; diff --git a/src/content/docs/basic/machines.md b/src/content/docs/basic/01-machines.md similarity index 100% rename from src/content/docs/basic/machines.md rename to src/content/docs/basic/01-machines.md diff --git a/src/content/docs/basic/networking.md b/src/content/docs/basic/02-networking.md similarity index 100% rename from src/content/docs/basic/networking.md rename to src/content/docs/basic/02-networking.md diff --git a/src/content/docs/basic/configuration.md b/src/content/docs/basic/03-configuration.md similarity index 100% rename from src/content/docs/basic/configuration.md rename to src/content/docs/basic/03-configuration.md diff --git a/src/content/docs/scope.md b/src/content/docs/create-scope.md similarity index 100% rename from src/content/docs/scope.md rename to src/content/docs/create-scope.md diff --git a/src/content/docs/get-started.md b/src/content/docs/get-started.md deleted file mode 100644 index b8c9a7c..0000000 --- a/src/content/docs/get-started.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Get Started -description: Get started with OtterScale. ---- - -Welcome to OtterScale! This guide will help you get up and running with the platform. - -## Introduction - -OtterScale is a powerful platform for managing your infrastructure and applications. - -## Prerequisites - -Before you begin, ensure you have the following: -- An account on OtterScale. -- Access to the necessary resources. - -## Next Steps - -Once you are set up, you can proceed to: -- [Manage Scopes](/scope) -- [Explore Basic Features](/basic/machines) -- [Deploy Applications](/application/applications) diff --git a/src/content/docs/getting-started/01-prerequisites.md b/src/content/docs/getting-started/01-prerequisites.md new file mode 100644 index 0000000..9b5b63f --- /dev/null +++ b/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)
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` | diff --git a/src/content/docs/getting-started/02-installation.md b/src/content/docs/getting-started/02-installation.md new file mode 100644 index 0000000..71246c0 --- /dev/null +++ b/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. diff --git a/src/content/docs/getting-started/03-scope.md b/src/content/docs/getting-started/03-scope.md new file mode 100644 index 0000000..8d62583 --- /dev/null +++ b/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 ● +- **Description**: Enter a unique name for your scope. +- **Input**: Text field (Required). + +#### Machine Selection + +- **Label**: Machine ● +- **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 next to a machine name displays detailed hardware specifications (CPU, Memory, Storage, System info, etc.). + +#### Storage Devices + +- **Label**: Storage Devices ● +- **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. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 36fd35c..c743575 100644 --- a/src/content/docs/index.mdx +++ b/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 diff --git a/src/content/docs/introduction.md b/src/content/docs/introduction.md new file mode 100644 index 0000000..2b5da66 --- /dev/null +++ b/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) diff --git a/src/content/docs/service/applications.md b/src/content/docs/service/01-applications.md similarity index 100% rename from src/content/docs/service/applications.md rename to src/content/docs/service/01-applications.md diff --git a/src/content/docs/service/compute.md b/src/content/docs/service/02-compute.md similarity index 100% rename from src/content/docs/service/compute.md rename to src/content/docs/service/02-compute.md diff --git a/src/content/docs/service/models.md b/src/content/docs/service/03-models.md similarity index 100% rename from src/content/docs/service/models.md rename to src/content/docs/service/03-models.md diff --git a/src/content/docs/service/storage.md b/src/content/docs/service/04-storage.md similarity index 100% rename from src/content/docs/service/storage.md rename to src/content/docs/service/04-storage.md diff --git a/src/content/docs/service/settings.md b/src/content/docs/service/05-settings.md similarity index 100% rename from src/content/docs/service/settings.md rename to src/content/docs/service/05-settings.md