Skip to main content

1. setup development environment

🐧 WSL Setup Guide cho Docker Webserver

📋 Yêu cầu hệ thống

Windows Requirements:

  • Windows 10/11 (Build 19041 trở lên)
  • WSL2 (Windows Subsystem for Linux 2)
  • Docker Desktop for Windows
  • Git for Windows

WSL Requirements:

  • Ubuntu 20.04+ hoặc Debian 11+
  • Docker Desktop for Windows với WSL2 backend
  • Git với SSH key setup
  • Make utility

🚀 Cài đặt WSL2

Bước 1: Enable WSL Features

# Mở PowerShell với quyền Administrator và chạy:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Bước 2: Restart Computer

Sau khi enable features, restart máy tính để áp dụng thay đổi.

Bước 3: Set WSL2 as Default

# Set WSL2 làm default
wsl --set-default-version 2

Bước 4: Install Ubuntu/Debian

# Cài đặt Ubuntu (khuyến nghị)
wsl --install -d Ubuntu

# Hoặc cài đặt Debian
wsl --install -d Debian

🔧 Cài đặt Docker Desktop

Bước 1: Download và Cài đặt Docker Desktop

  1. Tải Docker Desktop từ: https://www.docker.com/products/docker-desktop
  2. Cài đặt Docker Desktop với WSL2 backend
  3. Khởi động Docker Desktop

Bước 2: Cấu hình WSL2 Integration

  1. Mở Docker Desktop
  2. Vào Settings > Resources > WSL Integration
  3. Enable integration với WSL distribution của bạn (Ubuntu/Debian)
  4. Click Apply & Restart

Bước 3: Test Docker trong WSL

# Test Docker
docker --version
docker-compose --version

# Test Docker daemon
docker run hello-world

🔑 Setup GitLab Access

Bước 1: Generate SSH Key

# Tạo SSH key mới
ssh-keygen -t ed25519 -C "your-email@example.com"

# Hoặc sử dụng RSA (nếu cần tương thích)
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

Bước 2: Add SSH Key to SSH Agent

# Start SSH agent
eval "$(ssh-agent -s)"

# Add SSH key to agent
ssh-add ~/.ssh/id_ed25519

Bước 3: Copy Public Key

# Display public key
cat ~/.ssh/id_ed25519.pub

# Copy output và thêm vào GitLab

Bước 4: Add Key to GitLab

  1. Đăng nhập vào GitLab: https://gitlab.itvina.com
  2. Vào User Settings > SSH Keys
  3. Paste public key vào Key field
  4. Đặt Title (ví dụ: "WSL Development Machine")
  5. Click Add key

Bước 5: Test GitLab Connection

# Test SSH connection
ssh -T git@gitlab.itvina.com

# Nếu thành công sẽ hiển thị:
# Welcome to GitLab, @username!

🔑 Tạo GitLab Token

Bước 1: Đăng nhập GitLab

  1. Truy cập: https://gitlab.itvina.com
  2. Đăng nhập với tài khoản của bạn

Bước 2: Tạo Access Token

  1. Click vào Avatar (góc trên bên phải) > Preferences
  2. Chọn Access Tokens từ menu bên trái
  3. Điền thông tin:
    • Token name: docker-webserver-dev (hoặc tên bạn muốn)
    • Expiration date: Chọn ngày hết hạn (khuyến nghị 1 năm)
    • Scopes: Chọn các quyền cần thiết:
      • ✅ read_repository (để clone repositories)
      • ✅ read_api (để truy cập API)
      • ✅ write_repository (nếu cần push code)
  4. Click Create personal access token

Bước 3: Copy Token

  1. QUAN TRỌNG: Copy token ngay lập tức vì sẽ không hiển thị lại
  2. Token có dạng: glpat-xxxxxxxxxxxxxxxxxxxx
  3. Lưu token vào nơi an toàn (password manager, file text tạm thời)

Bước 4: Cấu hình Token trong .env

# Mở file .env
nano .env

# Hoặc sử dụng editor khác
code .env

# Thay thế dòng GITLAB_TOKEN bằng token thực tế:
GITLAB_TOKEN="glpat-YOUR_ACTUAL_TOKEN_HERE"

Bước 5: Test Token

# Test token bằng cách clone một repository private
git clone https://oauth2:YOUR_TOKEN@gitlab.itvina.com/sm/soft.git test-clone

# Nếu thành công, xóa thư mục test
rm -rf test-clone

📁 Setup Project Structure

Bước 1: Create Sources Directory

# Tạo thư mục Sources
mkdir -p /home/$USER/Sources
cd /home/$USER/Sources

Bước 2: Clone Docker Webserver

# Clone docker-webserver (thay thế URL thực tế)
git clone <docker-webserver-repo-url> docker-webserver
cd docker-webserver

Bước 3: Create Project Structure

# Tạo cấu trúc thư mục SAAS
mkdir -p ../saas
cd ../saas
git clone git@gitlab.itvina.com:sass/havico.git havico

# Tạo cấu trúc thư mục TMS
cd ..
mkdir -p TMS
cd TMS
git clone git@gitlab.itvina.com:tms/fleet.git fleet
git clone git@gitlab.itvina.com:tms/soft.git soft

# Tạo cấu trúc thư mục SM
cd ..
mkdir -p SM
cd SM
git clone git@gitlab.itvina.com:sm/customer_api.git customer_api
git clone git@gitlab.itvina.com:sm/customer_web.git customer_web
git clone git@gitlab.itvina.com:sm/soft.git soft
git clone git@gitlab.itvina.com:sm/import.git import

cd ..

⚙️ Cấu hình Environment

Bước 1: Create .env File

# Quay lại thư mục docker-webserver
cd docker-webserver

# Tạo file .env
touch .env

Bước 2: Configure .env Content

# Edit file .env với nội dung sau:
cat > .env << 'EOF'
# Cấu hình Nginx
NGINX_CONFIG_DIR="/etc/nginx/conf.d"

# Các domain cho SmartPost
DOMAIN_SOFT="tanphat.smartpost.vn.local sgw.smartpost.vn.local chien.smartpost.vn.local mekongpost.smartpost.vn.local trackingtanphat.smartpost.vn.local"
DOMAIN_API_SOFT="api.smartpost.vn.local debweb-sm-services.smartpost.vn.local"
DOMAIN_TRACKING="trackingtanphat.smartpost.vn.local trackingchien.smartpost.vn.local tracking-swg.smartpost.vn.local trackingnghia.smartpost.vn.local"
DOMAIN_CUSTOMER="thanhvien.smartpost.vn.local thanhvienmekong.smartpost.vn.local thanhvienchien.smartpost.vn.local app-sgw.smartpost.vn.local"
DOMAIN_API_CUSTOMER="apicustomer.smartpost.vn.local api-customer.smartpost.vn.local"
DOMAIN_IMPORT="import.smartpost.vn.local import.phanmemvantai.com.local"
DOMAIN_PAYMENT_SERVICE="payment.itvina.com.local"

# Các domain cho TMS
DOMAIN_TMS_SOFT="pm-nghia.phanmemvantai.com.local test.phanmemvantai.com.local"
DOMAIN_TMS_API="api.phanmemvantai.com.local api-test.phanmemvantai.com.local"

# Các domain cho Fleet
DOMAIN_FLEET_SOFT="quanlybaotrixe.com.local"
DOMAIN_FLEET_API="api.quanlybaotrixe.com.local"

# Các domain cho SAAS
DOMAIN_SAAS="havico.vn.local"

# Domain array tổng hợp
DOMAIN_ARRAY="pm-nghia.smartpost.vn.local tanphat.smartpost.vn.local sgw.smartpost.vn.local chien.smartpost.vn.local mekongpost.smartpost.vn.local api.smartpost.vn.local"

# IP local (sẽ được tự động phát hiện)
LOCAL_IP="192.168.1.142"

# GitLab token (thay thế bằng token thực tế)
GITLAB_TOKEN="glpat-YOUR_ACTUAL_TOKEN_HERE"
EOF

🚀 Khởi động Project

Bước 1: Setup Permissions

# Setup permissions cho tất cả scripts
make first-time-setup

# Hoặc chỉ setup permissions
make setup-permissions

Bước 2: Start Services

# Khởi động với IP tự động
make up

# Hoặc sử dụng script start
./start

🔍 Kiểm tra và Debug

Kiểm tra WSL Status

# Kiểm tra WSL version
wsl --list --verbose

# Kiểm tra WSL status
wsl --status

Kiểm tra Docker Status

# Kiểm tra Docker service
sudo service docker status

# Kiểm tra Docker containers
docker ps

# Kiểm tra Docker networks
docker network ls

Kiểm tra Project Structure

# Kiểm tra cấu trúc thư mục
tree /home/$USER/Sources/ -L 2

# Kiểm tra permissions
ls -la /home/$USER/Sources/docker-webserver/scripts/

Kiểm tra Network Configuration

# Kiểm tra IP detection
make test-ip

# Xem cấu hình hiện tại
make show-config

# Test IP detection script
./scripts/test-ip-detection.sh

🛠️ Troubleshooting

WSL Issues

# Restart WSL
wsl --shutdown
wsl

# Reset WSL (cẩn thận - sẽ xóa dữ liệu)
wsl --unregister Ubuntu
wsl --install -d Ubuntu

Docker Issues

# Restart Docker Desktop từ Windows
# Hoặc restart từ WSL
wsl --shutdown
wsl

# Cleanup Docker
docker system prune -a

# Check Docker status
docker info

# Nếu Docker Desktop không chạy, khởi động từ Windows

GitLab Issues

# Test SSH connection
ssh -T git@gitlab.itvina.com

# Check SSH key
ssh-add -l

# Regenerate SSH key if needed
ssh-keygen -t ed25519 -C "your-email@example.com"

# Test GitLab token
curl --header "PRIVATE-TOKEN: YOUR_TOKEN" "https://gitlab.itvina.com/api/v4/user"

# Nếu token hết hạn, tạo token mới từ GitLab
# Vào GitLab > Preferences > Access Tokens

Permission Issues

# Fix file permissions
chmod +x scripts/*.sh
chmod +x start

# Fix directory permissions
sudo chown -R $USER:$USER /home/$USER/Sources/

IP Detection Issues

# Manual IP configuration
make configure-wsl

# Test IP detection
make test-ip

# Debug IP detection
./scripts/test-ip-detection.sh

📝 Lưu ý quan trọng

File Paths

  • Sử dụng đường dẫn Linux trong WSL, không dùng Windows path
  • Ví dụ: /home/$USER/Sources/ thay vì C:\Users\...

Performance

  • WSL2 có performance tốt hơn WSL1 cho Docker
  • Đảm bảo đủ RAM cho Docker (ít nhất 4GB)
  • Sử dụng SSD để tăng tốc độ I/O

Security

  • GitLab Token: Không commit token vào git, chỉ lưu trong file .env
  • SSH Keys: Sử dụng SSH keys thay vì username/password
  • File Permissions: Đảm bảo file .env có permissions phù hợp
  • Token Expiration: Đặt lịch nhắc nhở khi token sắp hết hạn
  • Token Scope: Chỉ cấp quyền cần thiết cho token

Backup

  • Backup thường xuyên cấu hình và source code
  • Sử dụng git để version control
  • Backup SSH keys và certificates

🔗 Useful Commands

WSL Commands

# List WSL distributions
wsl --list --verbose

# Access specific distribution
wsl -d Ubuntu

# Shutdown WSL
wsl --shutdown

# Update WSL
wsl --update

Docker Commands

# Start Docker Desktop từ Windows
# Hoặc restart WSL để kết nối lại
wsl --shutdown
wsl

# Check Docker status
docker info

# Cleanup Docker
docker system prune -a

# List containers
docker ps

# List images
docker images

Project Commands

# Start project
make up

# Stop project
make down

# Restart project
make restart

# View logs
make logs

# Check configuration
make show-config
Back to top