wancat/linux-odyssey
1
0 Fork 0
mirror of https://github.com/linux-odyssey/linux-odyssey.git synced 2026-11-08 11:30:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: refine Windows setup instructions (#201)

Browse Source
This commit is contained in:
Justin Lin authored and GitHub committed 2026-09-26 10:35:48 +10:00
2 parents f1038e40f4 f0a279fa83
commit a037c7d512
1 file changed
+135 -78
Download Patch File Download Diff File Expand all files Collapse all files
docs/windows-setup.md
+135 -78
View File
@@ -1,141 +1,198 @@
# Windows Environment Setup # Windows Environment Setup
## Install WSL and Ubuntu ## 1. Install WSL and Ubuntu
Please refer to the Official [Setup WSL](https://learn.microsoft.com/en-us/windows/wsl/setup/environment) on Microsoft's website. Refer to Microsoft’s official [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install).
Run the following command in PowerShell as Administrator: Open PowerShell as Administrator and run:
```powershell
wsl --install wsl --install
Then restart the computer. After restarting, you can open Ubuntu terminal by searching "Ubuntu" in Start menu. You will be prompted to create a new user account. Once you have done that, you can continue with the following steps.
## Setup Environment (In Ubuntu terminal)
1. Update and upgrade
```
sudo apt-get update
sudo apt-get upgrade
``` ```
1. Install Git Restart your computer after the installation finishes.
``` Open Ubuntu from the Start menu. The first time Ubuntu starts, it will ask you to create a Linux username and password.
sudo apt-get install git
Verify that Ubuntu is using WSL 2 by running this command in PowerShell:
```powershell
wsl --update
wsl --list --verbose
``` ```
1. Install Node.js (Version 20.x) Ubuntu should show `2` in the `VERSION` column.
``` If it is using WSL 1, run:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install nodejs ```powershell
sudo apt install build-essential wsl --set-version Ubuntu 2
sudo npm install -g yarn
``` ```
## Install Docker ## 2. Install Docker Desktop
(Refer to [get.docker.com](https://get.docker.com/)) Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/).
To install the latest stable versions of Docker CLI, Docker Engine, and their Start Docker Desktop after installation.
dependencies:
1. Download the script Docker Desktop normally uses the WSL 2 engine automatically. If the `Use the WSL 2 based engine` option appears under `Settings > General`, ensure it is enabled.
``` Go to:
curl -fsSL https://get.docker.com -o install-docker.sh
```text
Settings > Resources > WSL Integration
``` ```
1. verify the script's content Enable integration with your Ubuntu distribution, then select **Apply & restart**.
``` If the WSL Integration section is unavailable, ensure Docker Desktop is using Linux containers.
cat install-docker.sh
```
1. run the script with --dry-run to verify the steps it executes > [!IMPORTANT]
> Do not separately install Docker Engine inside Ubuntu when using Docker Desktop. Having both installations may cause conflicts.
``` Open the Ubuntu terminal and verify that Docker is available:
sh install-docker.sh --dry-run
```
**NOTE: the script will recommend you to use Docker Desktop instead, but we need to use Docker inside WSL for the backend to work.** Just ignore it and wait for the installation to finish. ```bash
1. run the script either as root, or using sudo to perform the installation.
```
sudo sh install-docker.sh
```
1. Verify the installation
```
docker --version docker --version
docker compose version
docker run --rm hello-world
``` ```
1. Add your user to the docker group ## 3. Set Up the Ubuntu Environment
``` Run the following commands in the Ubuntu terminal.
sudo usermod -aG docker $USER
### Update the Package List
```bash
sudo apt update
``` ```
**NOTE: You need to create a new WSL terminal to apply the changes.** ### Install the Required Tools
1. Verify the installation
```bash
sudo apt install -y git curl ca-certificates build-essential
``` ```
docker ps
### Install Node.js 20
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
``` ```
This should return something like:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ### Install Yarn 1.22
## Run the Project (In Ubuntu terminal)
1. Clone the repository
```bash
sudo npm install -g yarn@1.22.22
``` ```
git clone https://github.com/lancatlin/linux-odyssey.git
Verify the installations:
```bash
git --version
node --version
npm --version
yarn --version
```
The Node.js version should be `20.x` or later, and the Yarn version should be `1.22.x`.
## 4. Clone the Project
> [!WARNING]
> Clone the repository into the WSL Linux filesystem, such as `~/projects`. Do not place it on a Windows-mounted drive such as `/mnt/c/...` or `/mnt/d/...`. The project uses a bind mount for MongoDB data, and Windows-mounted directories may cause permission and filesystem compatibility problems.
Create and enter a project directory:
```bash
mkdir -p <path-to-projects-directory>
cd <path-to-projects-directory>
```
Clone the repository:
```bash
git clone https://github.com/linux-odyssey/linux-odyssey.git
cd linux-odyssey cd linux-odyssey
``` ```
Optional: To open the project in VSCode, run the following command inside the project folder: ### Optional: Open the Project in VS Code
``` Install [Visual Studio Code](https://code.visualstudio.com/) and the **WSL** extension first. Then run:
```bash
code . code .
``` ```
1. Install dependencies ## 5. Install Project Dependencies
``` From the project root, run:
```bash
yarn install yarn install
``` ```
It is ok if there are some warnings and `gyp: ERR` errors, just verify there is `done` at the end.
1. Copy the environment variables Warnings during installation may be harmless. The installation succeeded if Yarn finishes with a `Done` message and does not display `error Command failed`.
``` If a `gyp` error appears, confirm that it belongs to an optional dependency before ignoring it.
## 6. Create the Environment File
Copy the sample environment file:
```bash
cp .env.sample .env cp .env.sample .env
``` ```
1. Docker setup Confirm that the file exists:
```bash
ls -la .env
``` ```
The default values are suitable for local development. Do not use the sample secret key in a production environment.
## 7. Start the Docker Services
Ensure Docker Desktop is running, then execute:
```bash
docker compose pull docker compose pull
docker compose build docker compose build
docker compose up -d db docker compose up -d
``` ```
<!-- Check folder ./config exist and is empty --> Check that the containers are running:
<!-- Check .env file exist -->
1. Run the project
```bash
docker compose ps
``` ```
yarn build
To stop the Docker services later:
```bash
docker compose down
```
## 8. Run the Project
Start the frontend and backend development servers:
```bash
yarn dev yarn dev
``` ```
<!-- Check ./config/ssh_key.pub is a file not a folder --> Keep the terminal running and open the following address in your browser:
Enjoy! [http://localhost:8000](http://localhost:8000)
To stop the development servers, press `Ctrl+C`.
### Optional: Verify the Production Build
You can verify that the project builds successfully by running:
```bash
yarn build
```