otterscale · iasthc · Dec 30, 2025 · Dec 30, 2025 · Dec 30, 2025 · Dec 30, 2025
@@ -12,19 +12,19 @@ import { Card, CardGrid, Aside, Badge } from '@astrojs/starlight/components';
 
 ## OtterScale Control Node
 
-Before installing OtterScale, ensure your environment meets the following specifications.
+The Control Node serves as the central management hub for your OtterScale deployment. Before proceeding with installation, verify that your designated control node machine meets the following requirements.
 
 ### Operating System
 
-This is a specific version of Linux. If you're using a different operating system, you'll need to install Ubuntu 24.04 LTS first.
+Install Ubuntu 24.04 LTS on your control node. If your machine runs a different OS, perform a clean installation of Ubuntu 24.04 LTS first.
 
 | Component | Requirement                     |
 | :-------- | :------------------------------ |
 | **OS**    | **Ubuntu 24.04 LTS** (Required) |
 
 ### Hardware Requirements
 
-These are the minimum requirements for the control node. More is always better for performance.
+Ensure your control node hardware meets or exceeds these minimum specifications. Higher resources will improve performance and stability.
 
 | Resource       | Minimum Requirement      |
 | :------------- | :----------------------- |
@@ -34,12 +34,12 @@ These are the minimum requirements for the control node. More is always better f
 
 ### Network Configuration
 
-The installer will help set up networking - no manual configuration needed.
+The OtterScale installer will automatically configure networking, but confirm the following prerequisites:
 
-- **Connectivity:** At least one network interface with external internet access.
-- **Bridge Configuration:** The installation script will check for network bridge `br-otters`.
-  - _Existing:_ If the bridge exists, it will be used.
-  - _Missing:_ If the bridge does not exist, the script will prompt to select an existing bridge or create a new one automatically.
+- **Connectivity:** Ensure at least one network interface has external internet access.
+- **Bridge Configuration:** The installer checks for a network bridge named `br-otters`.
+  - If it exists, the installer will use it.
+  - If not, you will be prompted to select an existing bridge or allow the installer to create one automatically.
 
 ---
 
@@ -50,23 +50,27 @@ The installer will help set up networking - no manual configuration needed.
 
 ## K8S Nodes (Server Nodes)
 
-Ensure the following settings are configured on your server hosts.
+K8S nodes are the servers that will form your Kubernetes cluster. These nodes must be commissioned via the OtterScale web interface after creating a Scope, and then provisioned. Ensure each server host is configured as follows before commissioning.
 
 ### BIOS Configuration
 
+Access your server's BIOS settings (typically by pressing F2, F10, or Del during boot) and configure the following settings:
+
 1.  **BMC Settings:**
-    - **BMC Static IP:** Set a static IP for the BMC to ensure stable management access.
-    - **Boot Order:** Enable BMC Network and prioritize **Network Boot** in the boot order.
+    - **BMC Static IP:** Assign a static IP address to the BMC for reliable remote management access.
+    - **Boot Order:** Enable network boot via BMC and set it as the highest priority in the boot order.
 2.  **Boot Options:**
-    - **Boot Mode:** Set to **UEFI**.
-      - **Why not Legacy?** Legacy mode is not recommended as it limits boot drive size to 2TB, lacks modern security features, and does not support GPT partitioning, which is standard for modern deployments.
-    - **Fast Boot:** **Disable** Fast Boot to ensure thorough hardware initialization.
+    - **Boot Mode:** Set to **UEFI** (recommended for modern deployments).
+      - Avoid Legacy mode, as it limits drive size to 2TB, lacks security features, and does not support GPT partitioning.
+    - **Fast Boot:** Disable Fast Boot to allow complete hardware initialization.
 3.  **CPU Virtualization:**
-    - **Intel:** Enable `VMX`, `VT-d`, or `VT-x`.
-    - **AMD:** Enable `SVM` or `AMD-V`.
+    - **Intel CPUs:** Enable `VMX`, `VT-d`, or `VT-x`.
+    - **AMD CPUs:** Enable `SVM` or `AMD-V`.
 
 ### Hardware Requirements
 
+Verify that each K8S node meets these storage requirements for optimal performance.
+
 | Resource    | Minimum Requirement                                 |
 | :---------- | :-------------------------------------------------- |
 | **Storage** | At least **2 Block disks** or **2 Physical drives** |
@@ -75,29 +79,27 @@ Ensure the following settings are configured on your server hosts.
 
 ## Network IP Requirement
 
-Ensure you have sufficient IP addresses available in your subnet.
+Plan your network IP allocation carefully to prevent conflicts. Ensure your subnet has sufficient available IP addresses for the OtterScale deployment.
 
 | Usage                   | Quantity | Description                                                                    |
 | :---------------------- | :------- | :----------------------------------------------------------------------------- |
-| **OS System**           | 1        | Used for the ingress controller.                                               |
-| **OtterScale**          | 1        | **Required from user.**A second IP in the same subnet for OtterScale services. |
+| **OS System**           | 1        | Reserved for the ingress controller.                                           |
+| **OtterScale**          | 1        | Required from user. A second IP in the same subnet for OtterScale services.    |
 | **Juju Controller**     | 1        | Used by the Canonical Juju controller.                                         |
 | **MAAS (DHCP)**         | 2        | Used for MAAS dynamic IP allocation.                                           |
-| **Kubernetes and Ceph** | 9 + N    | Used for Kubernetes and Ceph services.                                         |
+| **Kubernetes and Ceph** | 9 + N    | Used for Kubernetes and Ceph services (N = number of K8S nodes).               |
 
-**Total Estimated IPs:** 14 + N (where N is the number of servers)
+**Total Estimated IPs:** 14 + N (where N is the number of K8S nodes)
 
 ---
 
 <Aside>
-	**These firewall rules are for reference only.** Actual requirements depend on the applications
-	you install later. For easier management, consider using a dedicated VLAN instead of configuring
-	firewall rules on each machine.
+	These firewall rules are mandatory for the installation process. Ensure outbound access to the listed domains and ports is allowed on each node. For easier management, consider using a dedicated VLAN instead of configuring firewall rules on each machine.
 </Aside>
 
 ## Firewall Configuration
 
-The installation process requires outbound access to various external services. Please whitelist the following domains and ports.
+The OtterScale installation process requires outbound internet access to various external services. Configure your firewall to allow outbound connections to the following domains and ports on all nodes (Control Node and K8S nodes).
 
 <details>
 <summary>Canonical</summary>

@@ -5,50 +5,77 @@ description: Step-by-step guide to installing OtterScale.
 
 import { Steps, Aside } from '@astrojs/starlight/components';
 
-Follow the steps below to install and configure OtterScale.
+This guide provides a detailed, step-by-step process for installing OtterScale on your Control Node. Ensure you have completed all prerequisites outlined in the Prerequisites section before proceeding. The installation involves setting up dependencies, configuring the environment, and deploying the system.
+
+<Aside>
+	All commands should be run on the designated OtterScale Control Node with sudo privileges where required.
+</Aside>
 
 <Steps>
 
-1.  **Prepare apt package and docker**
+1.  ### **Install Required Packages and Docker**
+
+    Install essential tools and Docker, which are needed for cloning the repository and running containerized services.
 
     ```bash
+    sudo apt update
     sudo apt install -y git curl
     sudo snap install docker
     ```
 
-2.  **Git clone otterscale**
+2.  ### **Clone the OtterScale Repository**
+
+    Download the OtterScale source code from GitHub.
 
     ```bash
     git clone https://github.com/otterscale/otterscale.git
     ```
 
-3.  **Prepare and modify .env file**
+3.  ### **Configure the Environment File**
+
+    Navigate to the cloned directory and set up the environment configuration.
 
     ```bash
     cd otterscale
     cp .env.example .env
     ```
 
-    Update .env APP_VERSION and PUBLIC_API_URL
+    Edit the `.env` file to update the following variables:
+    - `APP_VERSION`: Set to the desired version (e.g., `0.6.0`).
+    - `PUBLIC_API_URL`: Set to your Control Node's IP address and port (e.g., `http://192.168.1.100:8299`). Replace `xx.xx.xx.xx` with your actual IP.
+
+    You can edit the file using a text editor like `nano`:
 
     ```bash
-    APP_VERSION=0.6.0
-    PUBLIC_API_URL=http://xx.xx.xx.xx:8299
+    nano .env
     ```
 
-4.  **Start Services**
+4.  ### **Start OtterScale Services**
 
-    Run the following command to start the necessary services using Docker Compose:
+    Launch the necessary services in the background using Docker Compose.
 
     ```bash
     sudo docker-compose up -d
     ```
 
-5.  **Run Installation Script**
+    Verify that the services are running:
 
-    Execute the installation script through the User Interface:
+    ```bash
+    sudo docker-compose ps
+    ```
+
+5.  ### **Execute the Installation Script**
+
+    Complete the installation via the web interface.
 
-    1.  Access the OtterScale UI.
-    2.  Copy the CLI from OtterScale UI and execute the command with sudo privilege.
+    1. Open your web browser and access the OtterScale UI at the `PUBLIC_API_URL` you configured (e.g., `http://192.168.1.100:8299`).
+    2. In the UI, locate and copy the installation CLI command.
+    3. Paste and run the command in your terminal with sudo privileges.
+
+    If you encounter any issues during execution, first verify your Firewall Configuration as outlined in the Prerequisites section. Additionally, check the `setup.log` file in the current directory for detailed error information.
 
 </Steps>
+
+<Aside>
+	Upon successful completion, your OtterScale system will be operational. Proceed to the next guide for configuration and usage.
+</Aside>