mirror of
https://github.com/linux-odyssey/linux-odyssey.git
synced 2026-11-06 03:20:13 +08:00
200 lines
4.2 KiB
Markdown
200 lines
4.2 KiB
Markdown
# Windows Environment Setup
|
||
|
||
## 1. Install WSL and Ubuntu
|
||
|
||
Refer to Microsoft’s official [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install).
|
||
|
||
Open PowerShell as Administrator and run:
|
||
|
||
```powershell
|
||
wsl --install
|
||
```
|
||
|
||
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.
|
||
|
||
Verify that Ubuntu is using WSL 2 by running this command in PowerShell:
|
||
|
||
```powershell
|
||
wsl --update
|
||
wsl --list --verbose
|
||
```
|
||
|
||
Ubuntu should show `2` in the `VERSION` column.
|
||
|
||
If it is using WSL 1, run:
|
||
|
||
```powershell
|
||
wsl --set-version Ubuntu 2
|
||
```
|
||
|
||
## 2. Install Docker Desktop
|
||
|
||
Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/).
|
||
|
||
Start Docker Desktop after installation.
|
||
|
||
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:
|
||
|
||
```text
|
||
Settings > Resources > WSL Integration
|
||
```
|
||
|
||
Enable integration with your Ubuntu distribution, then select **Apply & restart**.
|
||
|
||
If the WSL Integration section is unavailable, ensure Docker Desktop is using Linux containers.
|
||
|
||
> [!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:
|
||
|
||
```bash
|
||
docker --version
|
||
docker compose version
|
||
docker run --rm hello-world
|
||
```
|
||
|
||
## 3. Set Up the Ubuntu Environment
|
||
|
||
Run the following commands in the Ubuntu terminal.
|
||
|
||
### Update the Package List
|
||
|
||
```bash
|
||
sudo apt update
|
||
```
|
||
|
||
### Install the Required Tools
|
||
|
||
```bash
|
||
sudo apt install -y git curl ca-certificates build-essential
|
||
```
|
||
|
||
### Install Node.js 20
|
||
|
||
```bash
|
||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||
sudo apt install -y nodejs
|
||
```
|
||
|
||
### Install Bun
|
||
|
||
```bash
|
||
curl -fsSL https://bun.sh/install | bash
|
||
```
|
||
|
||
Restart your terminal (or run `source ~/.bashrc`) so `bun` is on your `PATH`.
|
||
|
||
Verify the installations:
|
||
|
||
```bash
|
||
git --version
|
||
node --version
|
||
bun --version
|
||
```
|
||
|
||
The Node.js version should be `20.x` or later, and the Bun version should be `1.3` or later.
|
||
|
||
## 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
|
||
```
|
||
|
||
### Optional: Open the Project in VS Code
|
||
|
||
Install [Visual Studio Code](https://code.visualstudio.com/) and the **WSL** extension first. Then run:
|
||
|
||
```bash
|
||
code .
|
||
```
|
||
|
||
## 5. Install Project Dependencies
|
||
|
||
From the project root, run:
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
Warnings during installation may be harmless. The installation succeeded if Bun finishes with an `installed` message and does not display an `error:` message.
|
||
|
||
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
|
||
```
|
||
|
||
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 build
|
||
docker compose up -d
|
||
```
|
||
|
||
Check that the containers are running:
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
To stop the Docker services later:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
## 8. Run the Project
|
||
|
||
Start the frontend and backend development servers:
|
||
|
||
```bash
|
||
bun run dev
|
||
```
|
||
|
||
Keep the terminal running and open the following address in your browser:
|
||
|
||
[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
|
||
bun run build
|
||
```
|