diff --git a/docs/en/2403_lts_sp3/_toc.yaml b/docs/en/2403_lts_sp3/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..fd5414ac7b55fa12e99d131490a9adcb99731ca8 --- /dev/null +++ b/docs/en/2403_lts_sp3/_toc.yaml @@ -0,0 +1,10 @@ +label: EulerLauncher User Guide +isManual: true +description: High-performance development resources on mainstream desktop OSs. +sections: + - label: Overview + href: ./overall.md + - label: Installing and Running EulerLauncher on Windows + href: ./win_user_manual.md + - label: Installing and Running EulerLauncher on macOS + href: ./mac_user_manual.md diff --git a/docs/en/2403_lts_sp3/images/mac-content.jpg b/docs/en/2403_lts_sp3/images/mac-content.jpg new file mode 100644 index 0000000000000000000000000000000000000000..4b9f101056fb7bde536342896b94a698e72889a2 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/mac-content.jpg differ diff --git a/docs/en/2403_lts_sp3/images/mac-install.jpg b/docs/en/2403_lts_sp3/images/mac-install.jpg new file mode 100644 index 0000000000000000000000000000000000000000..b710de9b24b76c35017cee591bc704750855781d Binary files /dev/null and b/docs/en/2403_lts_sp3/images/mac-install.jpg differ diff --git a/docs/en/2403_lts_sp3/images/mac-start.jpg b/docs/en/2403_lts_sp3/images/mac-start.jpg new file mode 100644 index 0000000000000000000000000000000000000000..2805c6244da9d1409958e8c33fc5296b1e138856 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/mac-start.jpg differ diff --git a/docs/en/2403_lts_sp3/images/mac-terminal.jpg b/docs/en/2403_lts_sp3/images/mac-terminal.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d0f3082cc64658afd888a02ca578f76857578f83 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/mac-terminal.jpg differ diff --git a/docs/en/2403_lts_sp3/images/mac-visudo.jpg b/docs/en/2403_lts_sp3/images/mac-visudo.jpg new file mode 100644 index 0000000000000000000000000000000000000000..7466ef4fec0f928ca0c0255ba59b628251216eb1 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/mac-visudo.jpg differ diff --git a/docs/en/2403_lts_sp3/images/win-install.jpg b/docs/en/2403_lts_sp3/images/win-install.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e395f62c0eb29390c980853f1d51ceb09641001e Binary files /dev/null and b/docs/en/2403_lts_sp3/images/win-install.jpg differ diff --git a/docs/en/2403_lts_sp3/images/win-terminal-1.jpg b/docs/en/2403_lts_sp3/images/win-terminal-1.jpg new file mode 100644 index 0000000000000000000000000000000000000000..5976bff82cd34b6195f11291d0a99341133cfce3 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/win-terminal-1.jpg differ diff --git a/docs/en/2403_lts_sp3/images/win-terminal-2.jpg b/docs/en/2403_lts_sp3/images/win-terminal-2.jpg new file mode 100644 index 0000000000000000000000000000000000000000..a831c6972f99a30355f68e34f30e09be237f0723 Binary files /dev/null and b/docs/en/2403_lts_sp3/images/win-terminal-2.jpg differ diff --git a/docs/en/2403_lts_sp3/mac_user_manual.md b/docs/en/2403_lts_sp3/mac_user_manual.md new file mode 100644 index 0000000000000000000000000000000000000000..979f9ea1d3a8eb33b2437d312266fa9a5728447c --- /dev/null +++ b/docs/en/2403_lts_sp3/mac_user_manual.md @@ -0,0 +1,234 @@ +# Installing and Running EulerLauncher on macOS + +## Preparations + +### Installing Homebrew + +Homebrew is the software package manager for macOS, which provides many practical functions, such as installation, uninstallation, update, viewing, and search. It allows you to use a simple command to manage packages without considering dependencies and file paths. + +On the macOS desktop, press **Shift**+**Command**+**U** to open the **Utilities** folder in **Go** and find **Terminal.app**. + +![](./images/mac-terminal.jpg) + +Install Homebrew based on the network status. + +Run the following command to install Homebrew: + +``` Shell +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +Alternatively, run the following command to install Homebrew: + +``` Shell +/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)" +``` + +### Installing QEMU and Wget + +EulerLauncher depends on QEMU to run on macOS, and image download depends on Wget. Homebrew can be used to easily download and manage such software. Run the following command to install QEMU and Wget: + +``` Shell +brew install qemu +brew install wget +``` + +### Configuring the sudo Password-Free Permission + +EulerLauncher depends on QEMU to run on macOS. To improve user network experience, [vmnet framework][1] of macOS is used to provide VM network capabilities. Currently, administrator permissions are required for using vmnet. When using the QEMU backend to create VMs with vmnet network devices, you need to enable the administrator permission. EulerLauncher automatically uses the `sudo` command to implement this process during startup. Therefore, you need to configure the `sudo` password-free permission for the current user. If you do not want to perform this configuration, please stop using EulerLauncher. + +1. On the macOS desktop, press **Shift**+**Command**+**U** to open the **Utilities** folder in **Go** and find **Terminal.app**. + + ![](./images/mac-terminal.jpg) + +2. Enter `sudo visudo` in the terminal to modify the sudo configuration file. Note that you may be required to enter the password in this step. Enter the password as prompted. + +3. Find and replace `%admin ALL=(ALL) ALL` with `%admin ALL=(ALL) NOPASSWD: ALL`. + + ![](./images/mac-visudo.jpg) + +4. Press **ESC** and enter **:wq** to save the settings. + +## Installing EulerLauncher + +EulerLauncher supports macOS Ventura for Apple Silicon and x86 architectures. [Download the latest version of EulerLauncher][1] for macOS and decompress it to the desired location. + +The directory generated after the decompression contains the following files: + +![](./images/mac-content.jpg) + +**install.exe** is the installation file, which is used to install the support files required by EulerLauncher to the specified location. **EulerLauncher.dmg** is the disk image of the main program. + +1. This operation requires the `sudo` permission. You need to [configure the sudo password-free permission](#configuring-the-sudo-password-free-permission) first. +2. Install the support files. Double-click the **install** file and wait until the program execution is completed. + +3. Configure EulerLauncher. + + - Check the locations of QEMU and Wget. The name of the QEMU binary file varies according to the architecture. Select the correct name (Apple Silicon: **qemu-system-aarch64**; Intel: **qemu-system-x86_64**) as required. + + ``` Shell + which wget + which qemu-system-{host_arch} + ``` + + Reference output: + + ```shell + /opt/homebrew/bin/wget + /opt/homebrew/bin/qemu-system-aarch64 + ``` + + Record the paths, which will be used in the following steps. + + - Open the **eulerlauncher.conf** file and configure it. + + ```shell + sudo vi /Library/Application\ Support/org.openeuler.eulerlauncher/eulerlauncher.conf + ``` + + EulerLauncher configurations are as follows: + + ```ini + [default] + log_dir = # Log file location (xxx.log) + work_dir = # EulerLauncher working directory, which is used to store VM images and VM files. + wget_dir = # Path of the Wget executable file. Set this parameter based on the previous step. + qemu_dir = # Path of the QEMU executable file. Set this parameter based on the previous step. + debug = True + + [vm] + cpu_num = 1 # Number of CPUs of the VM. + memory = 1024 #Memory size of the VM, in MB. Do not set this parameter to a value greater than 2048 for M1 users. + ``` + + Save the modifications and exit. + +4. Install **EulerLauncher.app**. + + - Double-click **EulerLauncher.dmg**. In the displayed window, drag **EulerLauncher.app** to **Applications** to complete the installation. You can find **EulerLauncher.app** in applications. + + ![](./images/mac-install.jpg) + +## Using EulerLauncher + +1. Find **EulerLauncher.app** in applications and click to start the program. + +2. EulerLauncher needs to access the network. When the following dialog box is displayed, click **Allow**. + + ![](./images/mac-start.jpg) + +3. Currently, EulerLauncher can be accessed only in CLI mode. Open **Terminal.app** and use the CLI to perform operations. + +### Operations on Images + +1. List available images. + + ```Shell + eulerlauncher images + ``` + + There are two types of EulerLauncher images: remote images and local images. Only local images in the **Ready** state can be used to create VMs. Remote images can be used only after being downloaded. You can also load a downloaded local image to EulerLauncher. For details, see the following sections. + +2. Download a remote image. + + ```Shell + eulerlauncher download-image 23.09 + + Downloading: 23.09, this might take a while, please check image status with "images" command. + ``` + + The image download request is an asynchronous request. The download is completed in the background. The time required depends on your network status. The overall image download process includes download, decompression, and format conversion. During the download, you can run the `image` command to view the download progress and image status at any time. + + ```Shell + eulerlauncher images + ``` + + When the image status changes to **Ready**, the image is downloaded successfully. The image in the **Ready** state can be used to create VMs. + + ```Shell + eulerlauncher images + ``` + +3. Load a local image. + + Load a custom image or an image downloaded to the local host to EulerLauncher to create a custom VM. + + ```Shell + eulerlauncher load-image --path {image_file_path} IMAGE_NAME + ``` + + The supported image formats are *xxx***.qcow2.xz** and *xxx***.qcow2**. + + Example: + + ```Shell + eulerlauncher load-image --path /opt/openEuler-23.09-x86_64.qcow2.xz 2309-load + + Loading: 2309-load, this might take a while, please check image status with "images" command. + ``` + + Load the **openEuler-23.09-x86_64.qcow2.xz** file in the **/opt** directory to the EulerLauncher system and name it **2309-load**. Similar to the download command, the load command is also an asynchronous command. You need to run the image list command to query the image status until the image status is **Ready**. Compared with directly downloading an image, loading an image is much faster. + + ```Shell + eulerlauncher images + ...... + + eulerlauncher images + ...... + ``` + +4. Delete an image. + + Run the following command to delete an image from the EulerLauncher system: + + ```Shell + eulerlauncher delete-image 2309-load + + Image: 2309-load has been successfully deleted. + ``` + +### Operations on VMs + +1. List VMs. + + ```shell + eulerlauncher list + + +----------+-----------+---------+---------------+ + | Name | Image | State | IP | + +----------+-----------+---------+---------------+ + | test1 | 2309-load | Running | 172.22.57.220 | + +----------+-----------+---------+---------------+ + | test2 | 2309-load | Running | N/A | + +----------+-----------+---------+---------------+ + ``` + + If the VM IP address is **N/A** and the VM status is **Running**, the VM is newly created and the network configuration is not complete. Configuring the network takes several seconds. You can obtain the VM information again later. + +2. Log in to a VM. + + If an IP address has been assigned to a VM, you can run the `ssh` command to log in to the VM. + + ```Shell + ssh root@{instance_ip} + ``` + + If the official image provided by the openEuler community is used, the default username is **root** and the default password is **openEuler12#$**. + +3. Create a VM. + + ```Shell + eulerlauncher launch --image {image_name} {instance_name} + ``` + + Use `--image` to specify an image and a VM name. + +4. Delete a VM. + + ```Shell + eulerlauncher delete-instance {instance_name} + ``` + +Delete a specified VM based on the VM name. + +[1]: https://developer.apple.com/documentation/vmnet diff --git a/docs/en/2403_lts_sp3/overall.md b/docs/en/2403_lts_sp3/overall.md new file mode 100644 index 0000000000000000000000000000000000000000..2aa3e7b5229e7733afd53ceac16bd7a7b5612680 --- /dev/null +++ b/docs/en/2403_lts_sp3/overall.md @@ -0,0 +1,18 @@ +# EulerLauncher + +EulerLauncher is a developer tool set incubated by the technical operation team and infrastructure team of the openEuler community. It integrates virtualization technologies (such as LXD, HyperV, and Virtualization Framework) in mainstream desktop operating systems (OSs). It utilizes VMs and container images officially released by the openEuler community to provide developers with unified development resource (such as VMs and containers) provisioning and management experience on Windows, macOS, and Linux, improving the convenience and stability of using the openEuler development environment on mainstream desktop OSs, as well as developer experience. + +## Background + +The convenience and stability of development resources (such as VMs and containers) provided by mainstream desktop OSs are important factors that affect the experience of openEuler developers, especially for individuals and university developers with limited development resources. Common VM management platforms have many limitations. For example, VirtualBox requires developers to download a large ISO image and install the OS, WSL cannot provide a real openEuler kernel, most VM management software does not fully support Apple Sillicon chips, and many software needs to be paid, greatly reducing developers' work efficiency. + +EulerLauncher provides a convenient, easy-to-use, and unified developer tool set on mainstream desktop OSs such as Windows, macOS, and Linux (planned). It supported the x86_64 and AArch64 hardware architectures, including Apple Sillicon chips. It also supports virtual hardware acceleration capabilities for different platforms, providing developers with high-performance development resources. EulerLauncher allows users to use VMs and container images (planned) released by the openEuler community, Daily Build images provided by the openEuler community, and other custom images that meet requirements, providing developers with multiple choices. + +## Quick Start + +For macOS users, see [Installing and Running EulerLauncher on macOS][1]. + +For Windows users, see [Installing and Running EulerLauncher in Windows][2]. + +[1]: ./mac_user_manual.md +[2]: ./win_user_manual.md diff --git a/docs/en/2403_lts_sp3/win_user_manual.md b/docs/en/2403_lts_sp3/win_user_manual.md new file mode 100644 index 0000000000000000000000000000000000000000..aa74f01b92d287da7c163e96f49ff6d862e47b32 --- /dev/null +++ b/docs/en/2403_lts_sp3/win_user_manual.md @@ -0,0 +1,159 @@ +# Installing and Running EulerLauncher on Windows + +EulerLauncher currently supports Windows 10/11. [Download the latest version of EulerLauncher][1] for Windows and decompress it to the desired location. +Right-click **config-env.bat** and choose **Run as administrator** from the shortcut menu. This script adds the current directory to the system environment variable `PATH`. If you know how to configure environment variables or the configuration script is incorrect, you can manually add the directory where the current script is located and the **qemu-img** subdirectory to the system environment variable `PATH`. + +To run EulerLauncher on Windows, you need to connect EulerLauncher to the Hyper-V virtualization backend. Hyper-V is a Microsoft hardware virtualization product that provides better performance for VMs on Windows. Before running EulerLauncher, check whether Hyper-V is enabled in your system. For details about how to check and enable Hyper-V, see [Install Hyper-V][2] or other network resources. + +The directory generated after the decompression contains the following files: + +- **eulerlauncherd.exe**: main process of EulerLauncher. It is a daemon process running in the background. It interacts with various virtualization backends and manages the life cycles of VMs, containers, and images. +- **eulerlauncher.exe**: EulerLauncher CLI client. You can use this client to interact with the eulerlauncherd daemon process and perform operations on VMs and images. +- **eulerlauncher.conf**: EulerLauncher configuration file, which must be stored in the same directory as **eulerlauncherd.exe**. Configure the file as follows: + +```ini +[default] +# Configure the directory for storing log files. +log_dir = D:\eulerlauncher-workdir\logs +# Whether to enable the debug log level. +debug = True +# Configure the EulerLauncher working directory. +work_dir = D:\eulerlauncher-workdir +# Configure the EulerLauncher image directory. The image directory is relative to the working directory. +image_dir = images +# Configure the VM file directory of EulerLauncher. The VM file directory is relative to the working directory. +instance_dir = instances +``` + +After the configuration is complete, right-click **eulerlauncherd.exe** and choose **Run as administrator** from the shortcut menu. **eulerlauncherd.exe** runs as a daemon process in the background. + +Start PowerShell or Command Prompt to prepare for the corresponding operation. + +## Exiting the eulerlauncherd Background Process on Windows + +After **eulerlauncherd.exe** is executed, the eulerlauncherd icon is displayed in the system tray in the lower right corner. Right-click the icon and choose **Exit EulerLauncher** from the shortcut menu to exit the eulerlauncherd background process. + +## Operations on Images + +1. List available images. + + ```PowerShell + eulerlauncher.exe images + + +-----------+----------+--------------+ + | Images | Location | Status | + +-----------+----------+--------------+ + | 22.03-LTS | Remote | Downloadable | + | 21.09 | Remote | Downloadable | + | 2203-load | Local | Ready | + +-----------+----------+--------------+ + ``` + + There are two types of EulerLauncher images: remote images and local images. Only local images in the **Ready** state can be used to create VMs. Remote images can be used only after being downloaded. You can also load a downloaded local image to EulerLauncher. For details, see the following sections. + +2. Download a remote image. + + ```PowerShell + eulerlauncher.exe download-image 23.09 + + Downloading: 23.09, this might take a while, please check image status with "images" command. + ``` + + The image download request is an asynchronous request. The download is completed in the background. The time required depends on your network status. The overall image download process includes download, decompression, and format conversion. During the download, you can run the `image` command to view the download progress and image status at any time. + + ```PowerShell + eulerlauncher.exe images + ``` + + When the image status changes to **Ready**, the image is downloaded successfully. The image in the **Ready** state can be used to create VMs. + + ```PowerShell + eulerlauncher.exe images + ``` + +3. Load a local image. + + Load a custom image or an image downloaded to the local host to EulerLauncher to create a custom VM. + + ```PowerShell + eulerlauncher.exe load-image --path {image_file_path} IMAGE_NAME + ``` + + The supported image formats are *xxx***.qcow2.xz** and *xxx***.qcow2**. + + Example: + + ```PowerShell + eulerlauncher.exe load-image --path D:\openEuler-23.09-x86_64.qcow2.xz 2309-load + + Loading: 2309-load, this might take a while, please check image status with "images" command. + ``` + + Load the **openEuler-23.09-x86_64.qcow2.xz** file in the **D:\\** directory to the EulerLauncher system and name it **2309-load**. Similar to the download command, the load command is also an asynchronous command. You need to run the image list command to query the image status until the image status is **Ready**. Compared with directly downloading an image, loading an image is much faster. + + ```PowerShell + eulerlauncher.exe images + + ...... + + eulerlauncher images + + ...... + ``` + +4. Delete an image. + + Run the following command to delete an image from the EulerLauncher system: + + ```PowerShell + eulerlauncher.exe delete-image 2309-load + + Image: 2309-load has been successfully deleted. + ``` + +## Operations on VMs + +1. List VMs. + + ```Powershell + eulerlauncher.exe list + + +----------+-----------+---------+---------------+ + | Name | Image | State | IP | + +----------+-----------+---------+---------------+ + | test1 | 2309-load | Running | 172.22.57.220 | + +----------+-----------+---------+---------------+ + | test2 | 2309-load | Running | N/A | + +----------+-----------+---------+---------------+ + ``` + + If the VM IP address is **N/A** and the VM status is **Running**, the VM is newly created and the network configuration is not complete. Configuring the network takes several seconds. You can obtain the VM information again later. + +2. Log in to a VM. + + If an IP address has been assigned to a VM, you can run the `ssh` command to log in to the VM. + + ```PowerShell + ssh root@{instance_ip} + ``` + + If the official image provided by the openEuler community is used, the default username is **root** and the default password is **openEuler12#$**. + +3. Create a VM. + + ```PowerShell + eulerlauncher.exe launch --image {image_name} {instance_name} + ``` + + Use `--image` to specify an image and a VM name. + +4. Delete a VM. + + ```PowerShell + eulerlauncher.exe delete-instance {instance_name} + ``` + + Delete a specified VM based on the VM name. + +[1]: https://gitee.com/openeuler/eulerlauncher/releases +[2]: https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v diff --git a/docs/zh/2403_lts_sp3/_toc.yaml b/docs/zh/2403_lts_sp3/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..c2f197a7917f4c05a34ad1193fb3f0dfa2346637 --- /dev/null +++ b/docs/zh/2403_lts_sp3/_toc.yaml @@ -0,0 +1,10 @@ +label: EulerLauncher 用户指南 +isManual: true +description: 为开发者提供在主流桌面操作系统上高性能的开发资源 +sections: + - label: 概述 + href: ./overall.md + - label: 在 Windows 下安装与运行 EulerLauncher + href: ./win_user_manual.md + - label: 在 MacOS 下安装与运行 EulerLauncher + href: ./mac_user_manual.md diff --git a/docs/zh/2403_lts_sp3/images/mac-content.jpg b/docs/zh/2403_lts_sp3/images/mac-content.jpg new file mode 100644 index 0000000000000000000000000000000000000000..4b9f101056fb7bde536342896b94a698e72889a2 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/mac-content.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/mac-install.jpg b/docs/zh/2403_lts_sp3/images/mac-install.jpg new file mode 100644 index 0000000000000000000000000000000000000000..b710de9b24b76c35017cee591bc704750855781d Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/mac-install.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/mac-start.jpg b/docs/zh/2403_lts_sp3/images/mac-start.jpg new file mode 100644 index 0000000000000000000000000000000000000000..2805c6244da9d1409958e8c33fc5296b1e138856 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/mac-start.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/mac-terminal.jpg b/docs/zh/2403_lts_sp3/images/mac-terminal.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d0f3082cc64658afd888a02ca578f76857578f83 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/mac-terminal.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/mac-visudo.jpg b/docs/zh/2403_lts_sp3/images/mac-visudo.jpg new file mode 100644 index 0000000000000000000000000000000000000000..7466ef4fec0f928ca0c0255ba59b628251216eb1 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/mac-visudo.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/win-install.jpg b/docs/zh/2403_lts_sp3/images/win-install.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e395f62c0eb29390c980853f1d51ceb09641001e Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/win-install.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/win-terminal-1.jpg b/docs/zh/2403_lts_sp3/images/win-terminal-1.jpg new file mode 100644 index 0000000000000000000000000000000000000000..5976bff82cd34b6195f11291d0a99341133cfce3 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/win-terminal-1.jpg differ diff --git a/docs/zh/2403_lts_sp3/images/win-terminal-2.jpg b/docs/zh/2403_lts_sp3/images/win-terminal-2.jpg new file mode 100644 index 0000000000000000000000000000000000000000..a831c6972f99a30355f68e34f30e09be237f0723 Binary files /dev/null and b/docs/zh/2403_lts_sp3/images/win-terminal-2.jpg differ diff --git a/docs/zh/2403_lts_sp3/mac_user_manual.md b/docs/zh/2403_lts_sp3/mac_user_manual.md new file mode 100644 index 0000000000000000000000000000000000000000..5ba1761c239085b4dbb3f189f7283d7c9f8cec1d --- /dev/null +++ b/docs/zh/2403_lts_sp3/mac_user_manual.md @@ -0,0 +1,241 @@ +# 在MacOS下安装与运行EulerLauncher + +## 准备工作 + +### 安装Homebrew + +Homebrew是一款Mac OS平台下的软件包管理工具，拥有安装、卸载、更新、查看、搜索等很多实用的功能。简单的一条指令，就可以实现包管理，而不用你关心各种依赖和文件路径的情况，十分方便快捷。 + +在MacOS桌面下敲击 `command` + `shift` + `u` 组合键，打开`访达`中的`实用工具`，并找到`终端.app`。 + + +并根据网络情况输入以下命令进行安装。 + +可以使用以下命令安装Homebrew: + +``` Shell +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +由于国内网络原因，可能需要修改源到国内源以进行安装： + +``` Shell +/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)" +``` + +### 安装Qemu及wget + +**EulerLauncher**在MacOS上运行依赖于`QEMU`，镜像下载依赖于`wget`，使用`Homebrew`可以非常方便的下载和管理此类软件，使用以下命令进行安装： + +``` Shell +brew install qemu +brew install wget +``` + +### 配置sudo免密码权限 + +**EulerLauncher**在MacOS上运行依赖于`QEMU`，为了使用户的网络体验更加优秀，因此采用了MacOS的[vmnet framework][1]来提供虚拟机的网络能力，当前`vmnet`使用时需要使用管理员权限，因此在使用`QEMU`后端创建带有`vmnet`类型网络设备的虚拟机时，需要启用管理员权限，EulerLauncher在启动时会自动使用`sudo`命令来实现这一过程，因此需要为当前用户配置`sudo`免密码使用权限，如您介意此配置，请停止使用EulerLauncher。 + +1. 在MacOS桌面下敲击 `command` + `shift` + `u` 组合键，打开`访达`中的`实用工具`，并找到`终端.app`。 + + +2. 在终端中输入`sudo visudo`修改sudo配置文件，注意，此步骤有可能要求输入密码，请按指示输入密码。 + +3. 找到并将`%admin ALL=(ALL) ALL`替换为 `%admin ALL=(ALL) NOPASSWD: ALL`。 + + +4. 敲击`ESC`，再输入`:wq`进行保存。 + +## 安装EulerLauncher + +**EulerLauncher**当前支持MacOS Ventura, 支持Apple Silicon芯片版及x86芯片版，前往[EulerLauncher最新版][1]下载MacOS版软件包并解压到期望的位置。 + +解压后的目录包含以下文件： + + + +其中`install`可执行文件为安装文件，用于将**EulerLauncher**所需支持文件安装到指定位置，`EulerLauncher.dmg`为主程序的磁盘映象。 + +1. 本操作需要sudo权限，请先完成[配置sudo免密码权限](#配置sudo免密码权限)操作。 + +2. 安装支持文件：双击`install`可执行文件，等待程序完成执行。 + +3. 配置**EulerLauncher**： + + - 查看`qemu`及`wget`所处位置，`qemu`二进制文件在不同架构下名称不同，请根据自身情况选择正确的名称(Apple Silicon: qemu-system-aarch64; Intel: qemu-system-x86_64)： + + ``` Shell + which wget + which qemu-system-{host_arch} + ``` + + 参考输出： + + ```bash + /opt/homebrew/bin/wget + /opt/homebrew/bin/qemu-system-aarch64 + ``` + + 查看完成后，记录路径结果，在接下来的步骤中将会使用到。 + + - 打开`eulerlauncher.conf`并进行配置： + + ``` Shell + sudo vi /Library/Application\ Support/org.openeuler.eulerlauncher/eulerlauncher.conf + ``` + + EulerLauncher的配置如下： + + ```bash + [default] + log_dir = # 日志文件位置(xxx.log) + work_dir = # EulerLauncher工作目录，用于存储虚拟机镜像、虚拟机文件等 + wget_dir = # wget的可执行文件路径，请参考上一步的内容进行配置 + qemu_dir = # qemu的可执行文件路径，请参考上一步的内容进行配置 + debug = True + + [vm] + cpu_num = 1 # 配置虚拟机的CPU个数 + memory = 1024 # 配置虚拟机的内存大小，单位为M，M1用户请勿配置超过2048 + ``` + + 完成编辑后保存退出。 + +4. 安装**EulerLauncher.app**: + + 双击`EulerLauncher.dmg`，在弹出的窗口中用鼠标将`EulerLauncher.app`拖动到`Applications`中，即可完成安装，并可在应用程序中找到`EulerLauncher.app`。 + + + +## 使用EulerLauncher + +1. 在应用程序中找到`EulerLauncher.app`，单击启动程序。 + +2. EulerLauncher需要访问网络，在弹出如下窗口时点击`允许`: + + + +3. EulerLauncher当前仅支持命令行方式进行访问，请打开`终端.app`，使用命令行进行操作。 + +### 镜像操作 + +1. 获取可用镜像列表： + + ```Shell + + eulerlauncher images + + ``` + + **EulerLauncher**镜像有两种位置属性：1）远端镜像 2）本地镜像，只有处于本地且状态为 `Ready` 的镜像可以直接用来创建虚拟机，位于远端的镜像需要下载后才能够使用；你也可以加载已经预先下载好的本地镜像到**EulerLauncher**中，具体操作方法可以参考接下来的操作指导。 + +2. 下载远端镜像。 + + ```Shell + eulerlauncher download-image 23.09 + + Downloading: 23.09, this might take a while, please check image status with "images" command. + ``` + + 镜像下载请求是一个异步请求，具体的下载动作将在后台完成，具体耗时与你的网络情况相关，整体的镜像下载流程包括下载、解压缩、格式转换等相关子流程，在下载过程中可以通过 `image` 命令随时查看下载进展与镜像状态： + + ```Shell + + eulerlauncher images + + ``` + + 当镜像状态转变为 `Ready` 时，表示镜像下载完成，处于 `Ready` 状态的镜像可被用来创建虚拟机： + + ```Shell + + eulerlauncher images + + ``` + +3. 加载本地镜像。 + + 用户也可以加载自定义镜像或预先下载到本地的镜像到EulerLauncher中用于创建自定义虚拟机： + + ```Shell + eulerlauncher load-image --path {image_file_path} IMAGE_NAME + ``` + + 当前支持加载的镜像格式有 `xxx.qcow2.xz`，`xxx.qcow2`。 + + 例如： + + ```Shell + eulerlauncher load-image --path /opt/openEuler-23.09-x86_64.qcow2.xz 2309-load + + Loading: 2309-load, this might take a while, please check image status with "images" command. + ``` + + 将位于 `/opt` 目录下的 `openEuler-23.09-x86_64.qcow2.xz` 加载到EulerLauncher系统中，并命名为 `2309-load`，与下载命令一样，加载命令也是一个异步命令，用户需要用镜像列表命令查询镜像状态直到显示为 `Ready`, 但相对于直接下载镜像，加载镜像的速度会快很多： + + ```Shell + eulerlauncher images + + ...... + + eulerlauncher images + + ...... + + ``` + +4. 删除镜像： + + 通过下面的命令将镜像从EulerLauncher系统中删除： + + ```Shell + eulerlauncher delete-image 2309-load + + Image: 2309-load has been successfully deleted. + ``` + +### 虚拟机操作 + +1. 获取虚拟机列表： + + ```shell + eulerlauncher list + + +----------+-----------+---------+---------------+ + | Name | Image | State | IP | + +----------+-----------+---------+---------------+ + | test1 | 2309-load | Running | 172.22.57.220 | + +----------+-----------+---------+---------------+ + | test2 | 2309-load | Running | N/A | + +----------+-----------+---------+---------------+ + ``` + + 若虚拟机IP地址显示为 `N/A` ，若这台虚拟机的状态为 `Running` 则表示这台虚拟机为新创建的虚拟机，网络还未配置完成，网络配置过程大概需要若干秒，请稍后重新尝试获取相关虚拟机信息。 + +2. 登录虚拟机： + + 若虚拟机已成功分配到IP地址，可以直接使用 `SSH` 命令进行登录： + + ```Shell + ssh root@{instance_ip} + ``` + + 若使用的是openEuler社区提供的官方镜像，则默认用户为 `root` 默认密码为 `openEuler12#$`。 + +3. 创建虚拟机。 + + ```Shell + eulerlauncher launch --image {image_name} {instance_name} + ``` + + 通过\-\-image指定镜像，同时指定虚拟机名称。 + +4. 删除虚拟机。 + + ```Shell + eulerlauncher delete-instance {instance_name} + ``` + + 根据虚拟机名称删除指定的虚拟机。 + + [1]: https://developer.apple.com/documentation/vmnet diff --git a/docs/zh/2403_lts_sp3/overall.md b/docs/zh/2403_lts_sp3/overall.md new file mode 100644 index 0000000000000000000000000000000000000000..1250b724e64281ed063f4fe80a6c1f05377db97b --- /dev/null +++ b/docs/zh/2403_lts_sp3/overall.md @@ -0,0 +1,18 @@ +# EulerLauncher + +**EulerLauncher**是由openEuler社区技术运营团队及基础设施团队孵化的开发者工具集，通过对主流桌面操作系统中的虚拟化技术(LXD、HyperV、Virtualization framework)等进行有机整合，使用openEuler社区官方发布的虚拟机、容器镜像，为开发者在Windows、MacOS、Linux上提供统一的开发资源(虚拟机、容器)发放和管理体验，提升主流桌面操作系统上openEuler开发环境使用的便利性和稳定性，有效提升开发者体验。 + +## 背景 & 简介 + +主流桌面操作系统上提供相关开发资源(虚拟机、容器等)的便利性和稳定性是影响openEuler开发者体验的重要因素，尤其是对开发资源受限的个人及高校开发者openEuler开发体验影响更为明显。当前常见的虚拟机管理平台有诸多局限性，如VirtualBox需要下载体积庞大的ISO镜像，同时需要进行操作系统安装等相关操作，WSL无法提供真实的openEuler内核，绝大多数虚拟机管理软件目前对Apple Sillicon芯片支持尚不完善且众多软件需要付费等，这些都极大的降低了开发者的工作效率。 + +**EulerLauncher**支持在Windows、MacOS及Linux(规划中)等主流桌面操作系统上提供方便、易用、统一体验的开发者工具集，硬件架构支持x86_64及Aarch64(包含Apple Sillicon系列芯片)；并支持各平台对应的虚拟化硬件加速能力，为开发者提供高性能的开发资源。**EulerLauncher**支持使用openEuler社区发布的虚拟机、容器(规划中)镜像、openEuler社区提供的Daily Build镜像以及其他符合要求的自定义镜像，为开发者提供多种选择。 + +## 快速开始 + +**EulerLauncher** MacOS用户请参考[《MacOS用户指导文档》][1] + +**EulerLauncher** Windows用户请参考[《Windows用户指导文档》][2] + +[1]: ./mac_user_manual.md +[2]: ./win_user_manual.md diff --git a/docs/zh/2403_lts_sp3/win_user_manual.md b/docs/zh/2403_lts_sp3/win_user_manual.md new file mode 100644 index 0000000000000000000000000000000000000000..29c8e12839c0e37089a1ae9c6a8787015d3a0f0f --- /dev/null +++ b/docs/zh/2403_lts_sp3/win_user_manual.md @@ -0,0 +1,162 @@ +# 在Windows下安装与运行EulerLauncher + +**EulerLauncher**当前支持Windows11/10，前往[EulerLauncher最新版下载][1]下载Windows版软件包并解压到期望的位置。 +右键点击 `config-env.bat` 并选择**以管理员身份运行**，该脚本将进行环境变量相关的配置，将当前目录添加到系统环境变量 `PATH`中，如果使用者掌握如何配置环境变量，或配置脚本出现问题，也可以进行手动配置，将当前脚本所在目录及 `qemu-img` 子目录添加至系统环境变量 `PATH` 中。 + +**EulerLauncher**在Windows上运行需要对接 `Hyper-V` 虚拟化后端，`Hyper-V` 是 Microsoft 的硬件虚拟化产品，可以为Windows上的虚拟机提供更为出色的性能。在运行**EulerLauncher**前，请先检查你的系统是否开启了 `Hyper-V`以及新建虚拟交换机，具体检查及开启方法请参考[Hyper-V开启指导][2]或其他网络资源。 + +**EulerLauncher**解压后包含以下几个部分： + +- eulerlauncherd.exe：EulerLauncher的主进程，是运行在后台的守护进程，负责与各类虚拟化后端交互，管理虚拟机、容器以及镜像的生命周期，eulerlauncherd.exe是运行在后台的守护进程。 +- eulerlauncher.exe：EulerLauncher的CLI客户端，用户通过该客户端与eulerlauncherd守护进程交互，对虚拟机、镜像等进行相关操作。 +- eulerlauncher.conf：EulerLauncher配置文件，需与eulerlauncherd.exe放置于同一目录下，参考下面配置进行相应配置： + +```Conf +[default] +# 配置日志文件的存储目录 +log_dir = D:\eulerlauncher-workdir\logs +# 配置日志等级是否开启Debug +debug = True +# 配置EulerLauncher的工作目录 +work_dir = D:\eulerlauncher-workdir +# 配置EulerLauncher的镜像目录，镜像目录为对工作目录的相对目录 +image_dir = images +# 配置EulerLauncher的虚拟机文件目录，虚拟机文件目录为对工作目录的相对目录 +instance_dir = instances +``` + +配置完成后请右键点击eulerlauncherd.exe，选择以管理员身份运行，点击后omnivird.exe将以守护进程的形式在后台运行。 + +打开 `PowerShell` 或 `Terminal` ，准备进行对应的操作。 + +## Windows下退出eulerlauncherd后台进程 + +当eulerlauncherd.exe运行后，会在操作系统右下角托盘区域生成eulerlauncherd托盘图标，鼠标右键点击托盘图标，并选择 `Exit eulerlauncher` 即可退出eulerlauncherd后台进程。 + +## 镜像操作 + +1. 获取可用镜像列表。 + + ```PowerShell + eulerlauncher.exe images + + +-----------+----------+--------------+ + | Images | Location | Status | + +-----------+----------+--------------+ + | 22.03-LTS | Remote | Downloadable | + | 21.09 | Remote | Downloadable | + | 2203-load | Local | Ready | + +-----------+----------+--------------+ + ``` + + **EulerLauncher**镜像有两种位置属性：1）远端镜像 2）本地镜像，只有处于本地且状态为 `Ready` 的镜像可以直接用来创建虚拟机，位于远端的镜像需要下载后才能够使用；你也可以加载已经预先下载好的本地镜像到**EulerLauncher**中，具体操作方法可以参考接下来的操作指导。 + +2. 下载远端镜像。 + + ```PowerShell + eulerlauncher.exe download-image 23.09 + + Downloading: 23.09, this might take a while, please check image status with "images" command. + ``` + + 镜像下载请求是一个异步请求，具体的下载动作将在后台完成，具体耗时与你的网络情况相关，整体的镜像下载流程包括下载、解压缩、格式转换等相关子流程，在下载过程中可以通过 `image` 命令随时查看下载进展与镜像状态： + + ```PowerShell + eulerlauncher.exe images + + ``` + + 当镜像状态转变为 `Ready` 时，表示镜像下载完成，处于 `Ready` 状态的镜像可被用来创建虚拟机： + + ```PowerShell + eulerlauncher.exe images + + ``` + +3. 加载本地镜像。 + + 用户也可以加载自定义镜像或预先下载到本地的镜像到EulerLauncher中用于创建自定义虚拟机： + + ```PowerShell + eulerlauncher.exe load-image --path {image_file_path} IMAGE_NAME + ``` + + 当前支持加载的镜像格式有 `xxx.qcow2.xz`，`xxx.qcow2`。 + + 例如： + + ```PowerShell + eulerlauncher.exe load-image --path D:\openEuler-23.09-x86_64.qcow2.xz 2309-load + + Loading: 2309-load, this might take a while, please check image status with "images" command. + ``` + + 将位于 `D:\` 目录下的 `openEuler-23.09-x86_64.qcow2.xz` 加载到EulerLauncher系统中，并命名为 `2309-load`，与下载命令一样，加载命令也是一个异步命令，用户需要用镜像列表命令查询镜像状态直到显示为 `Ready`， 但相对于直接下载镜像，加载镜像的速度会快很多： + + ```PowerShell + eulerlauncher.exe images + + ...... + + eulerlauncher images + + ...... + + ``` + +4. 删除镜像。 + + 通过下面的命令将镜像从EulerLauncher系统中删除： + + ```PowerShell + eulerlauncher.exe delete-image 2309-load + + Image: 2309-load has been successfully deleted. + ``` + +## 虚拟机操作 + +1. 获取虚拟机列表。 + + ```Powershell + eulerlauncher.exe list + + +----------+-----------+---------+---------------+ + | Name | Image | State | IP | + +----------+-----------+---------+---------------+ + | test1 | 2309-load | Running | 172.22.57.220 | + +----------+-----------+---------+---------------+ + | test2 | 2309-load | Running | N/A | + +----------+-----------+---------+---------------+ + ``` + + 若虚拟机IP地址显示为 `N/A` ，若这台虚拟机的状态为 `Running` 则表示这台虚拟机为新创建的虚拟机，网络还未配置完成，网络配置过程大概需要若干秒，请稍后重新尝试获取相关虚拟机信息。 + +2. 登录虚拟机。 + + 若虚拟机已成功分配到IP地址，可以直接使用 `SSH` 命令进行登录： + + ```PowerShell + ssh root@{instance_ip} + ``` + + 若使用的是openEuler社区提供的官方镜像，则默认用户为 `root` 默认密码为 `openEuler12#$`。 + +3. 创建虚拟机。 + + ```PowerShell + eulerlauncher.exe launch --image {image_name} {instance_name} + ``` + + 通过\-\-image指定镜像，同时指定虚拟机名称。 + +4. 删除虚拟机。 + + ```PowerShell + eulerlauncher.exe delete-instance {instance_name} + ``` + + 根据虚拟机名称删除指定的虚拟机。 + + [1]: https://gitee.com/openeuler/eulerlauncher/releases + [2]: https://learn.microsoft.com/zh-cn/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v