4.1 KiB
Windows Environment Setup
1. Install WSL and Ubuntu
Refer to Microsoft’s official WSL installation guide.
Open PowerShell as Administrator and run:
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:
wsl --update
wsl --list --verbose
Ubuntu should show 2 in the VERSION column.
If it is using WSL 1, run:
wsl --set-version Ubuntu 2
2. Install Docker Desktop
Install Docker Desktop for Windows.
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:
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:
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
sudo apt update
Install the Required Tools
sudo apt install -y git curl ca-certificates build-essential
Install Bun
curl -fsSL https://bun.sh/install | bash
Restart your terminal (or run source ~/.bashrc) so bun is on your PATH.
Verify the installations:
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:
mkdir -p <path-to-projects-directory>
cd <path-to-projects-directory>
Clone the repository:
git clone https://github.com/linux-odyssey/linux-odyssey.git
cd linux-odyssey
Optional: Open the Project in VS Code
Install Visual Studio Code and the WSL extension first. Then run:
code .
5. Install Project Dependencies
From the project root, run:
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:
cp .env.sample .env
Confirm that the file exists:
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:
docker compose pull
docker compose build
docker compose up -d
Check that the containers are running:
docker compose ps
To stop the Docker services later:
docker compose down
8. Run the Project
Start the frontend and backend development servers:
bun run dev
Keep the terminal running and open the following address in your browser:
To stop the development servers, press Ctrl+C.
Optional: Verify the Production Build
You can verify that the project builds successfully by running:
bun run build