eliott/Olares

Fork 0

Files

Meow33 51a06f8964 docs: update relevant docs

2026-01-07 16:58:18 +08:00

10 KiB

Raw Blame History

outline, description

outline

description

Guide to installing Olares on Windows using WSL (Windows Subsystem for Linux) including setup requirements and activation steps.

Install Olares on Windows via the script

This guide explains how to install Olares on Windows (WSL 2) using the provided installation script.

:::warning Not recommended for production use Currently, Olares on Windows has certain limitations including:

Lack of distributed storage support
Inability to add local nodes.

We recommend using it only for development or testing purposes. :::

System compatibility

Make sure your Windows meets the following requirements.

Required specifications

CPU: At least 4 cores
RAM: At least 16 GB of available memory
Storage: At least 150 GB of available SSD storage. ::: warning SSD required The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD. :::
Supported systems:
- Windows 10 or 11
- Linux (on WSL 2): Ubuntu 22.04 LTS or later; Debian 12 or later

Optional hardware

A GPU is not required to install Olares, but is necessary for AI applications.

GPU (NVIDIA only):
- Architecture: Turing or newer (e.g., GTX 16 series, RTX 20 series, and later).
- Verification:
  1. Open Task Manager > Performance to confirm your GPU model (must be NVIDIA).
  2. Run nvidia-smi inside your WSL terminal to confirm the driver is accessible.

Set up system environment

Enable the required Windows features for virtualization.

a. Open Control Panel, then go to Programs > Programs and Features > Turn Windows features on or off.

b. In the Windows Features window, check:
- Hyper-V (not required for Windows 10 Home and Windows 11 Home)
- Windows Subsystem for Linux
- Virtual Machine Platform
c. Click OK and restart your computer when prompted.

Set the execution policy for the current user.

a. Open PowerShell as administrator, then run the following command:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

b. When prompted to check whether to change the execution policy, type A and press Enter to confirm.

Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose
you to the security risks described in the about_Execution_Policies help topic at
https:/go.microsoft.com/fwlink/?LinkID-135170. Do you want to change the execution policy?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"):

Install Olares

Click https://windows.olares.sh to download the installation script publicInstall.latest.ps1.
Execute the script.

a. Open PowerShell as administrator, then navigate to the folder where the script is located. For example, if the script is in the Downloads folder, run the following command:
```
cd C:\Users\<YourUsername>\Downloads
```
b. Once in the correct folder, run the following command:
```
.\publicInstall.latest.ps1
```
:::warning Administrator privileges required Running PowerShell without administrator privileges will cause the installation to fail. See How to make sure I am using PowerShell as administrator. :::

When prompted with security warning, type R and press Enter to run the script once. The installation process for Olares will start.

Security warning
Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run
publicInstall.latest.ps1?
[D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"):

When prompted to select the drive to store the WSL Ubuntu distro, type the drive letter of an available disk. Ensure the selected drive has at least 80 GB of free space.

Installing Olares will create a WSL Ubuntu Distro and occupy at least 80 GB of disk space.
Please select the drive where you want to install it.

Available drives and free space:
C:\  Free Disk: 391.07 GB
D:\  Free Disk: 281.32 GB

Please enter the drive letter (e.g., C):

When prompted with the firewall rules setup, type yes to automatically configure them, or type no to skip this step.
If you choose to skip, either disable Windows Firewall Defender, or manually add TCP inbound rules.
```
Accessing Olares requires setting up firewall rules, specifically adding TCP inbound rules for ports 80, 443, and 30180.
Do you want to set up the firewall rules? (yes/no):
```
When promoted to confirm the IP address of Windows, type Y to confirm, or R to re-enter.
```
The NAT gateway (the Windows host)'s IP is 192.168.50.136. Confirm [Y] or Re-enter [R]?
```
::: tip Obtain the IPv4 address of Windows You can get the IPv4 address in advance by running ipconfig in the Windows command line. :::

:::info Errors during installation? If an error occurs during installation, use the following command to uninstall first:

wsl --unregister ubuntu

After uninstalling, retry the installation by running the original installation command. :::

FAQ

How to make sure I am using PowerShell as administrator?

You can confirm that PowerShell is running as an administrator if you see "Administrator: Windows PowerShell" in the title bar of the PowerShell window.

{width=70%}

If not, use one of the following methods:

Search for "PowerShell" in the Start menu, right-click it, and select Run as administrator.
Or press Win + R, type powershell, and press Ctrl + Shift + Enter to open PowerShell as an administrator.

How to configure the CPU and memory for WLS?

When installing Olares in WSL, the default memory allocation is 12GB. But you can configure the memory before Olares installation, or adjust both memory and CPU settings after installation.

Adjust the memory setting before installation

For example, to allocate 16GB of memory:

Add a user variable with the following:
- Variable name: WSL_MEMORY
- Variable value: 16
Click OK to apply changes.

:::tip If you already have a PowerShell window open, changes to environment variables will not take effect in the current session. To ensure the updated environment variables are loaded, open a new PowerShell terminal as administrator, and then run the installation script. :::

Adjust memory and CPU settings after installation

After installation, a configuration file named .wslconfig will be created in the current user's home directory (C:\Users\<YourUsername>\). This file allows you to adjust memory and CPU settings. The default configuration looks like this:

[wsl2]
memory=12GB
swap=0GB

For example, to use 4 CPU cores:

Add the processors parameter to the file:

[wsl2]
memory=12GB
processors=4
swap=0GB

Save the .wslconfig file with your custom changes.
Close all running virtual machines by running the following command in PowerShell:
```
wsl --shutdown
```
Restart Olares by running:
```
wsl -d Ubuntu
```

It will take a few minutes for Olares services to restart.

How to reactivate Olares after the PC restarts?

Run the following command in PowerShell to restart the Olares service:

wsl -d Ubuntu

How to disable Windows Defender Firewall?

:::tip You can turn on Windows Defender Firewall when the Olares installation completes. ::: To completely disable the firewall:

Open Control Panel > System and Security > Windows Defender Firewall.
In the navigation pane, click Turn Windows Defender Firewall on or off.
Select Turn off Windows Defender Firewall for both private and public networks, then click OK.

How to manually set firewall rules?

If you choose not to configure firewall rules during installation, follow these steps to set them manually:

Open Control Panel > System and Security > Windows Defender Firewall.
In the navigation pane, select Advanced settings.
In the navigation pane, right-click Inbound Rules and select New Rule.
In the New Inbound Rule Wizard, select Port and click Next.
In Specific local ports, enter 80, 443, 30180, and click Next.
Select Allow the connection and click Next.