docs: Update CHANGELOG and README for deployment models and troubleshooting
- Added multi-platform deployment architecture details (Web App, PWA, DApp) to README.md. - Included comprehensive troubleshooting guides and fix scripts in README.md. - Enhanced CHANGELOG.md with new features, fixes, and improvements, including TypeScript error resolutions and updated documentation structure. - Revised development setup instructions in DEV_SETUP.md to reflect changes in script usage and environment variable setup.
This commit is contained in:
defiQUG
209
docs/WSL_SETUP.md
Normal file
209
docs/WSL_SETUP.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# WSL/Ubuntu Setup Guide
|
||||
|
||||
This project has been migrated to use WSL (Windows Subsystem for Linux) with Ubuntu for development. All scripts have been converted from PowerShell to bash.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Install WSL 2 with Ubuntu**
|
||||
```powershell
|
||||
# In PowerShell (as Administrator)
|
||||
wsl --install -d Ubuntu
|
||||
```
|
||||
|
||||
2. **Verify WSL Installation**
|
||||
```bash
|
||||
# In WSL/Ubuntu terminal
|
||||
wsl --version
|
||||
```
|
||||
|
||||
3. **Install Required Tools in WSL**
|
||||
```bash
|
||||
# Update package list
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Install Node.js 18+
|
||||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# Install Docker (if not already installed)
|
||||
# Follow: https://docs.docker.com/engine/install/ubuntu/
|
||||
|
||||
# Install netcat (for port checking)
|
||||
sudo apt install -y netcat-openbsd
|
||||
|
||||
# Install jq (for JSON parsing in scripts)
|
||||
sudo apt install -y jq
|
||||
|
||||
# Install bc (for calculations in scripts)
|
||||
sudo apt install -y bc
|
||||
```
|
||||
|
||||
## Script Migration
|
||||
|
||||
All PowerShell scripts (`.ps1`) have been converted to bash scripts (`.sh`):
|
||||
|
||||
| PowerShell Script | Bash Script | Description |
|
||||
|------------------|-------------|-------------|
|
||||
| `start-dev.ps1` | `start-dev.sh` | Start development servers |
|
||||
| `start-all.ps1` | `start-all.sh` | Start all services |
|
||||
| `check-status.ps1` | `check-status.sh` | Check service status |
|
||||
| `test-curl.ps1` | `test-curl.sh` | Test API endpoints |
|
||||
| `fix-frontend.ps1` | `fix-frontend.sh` | Fix frontend issues |
|
||||
| `setup-database.ps1` | `setup-database.sh` | Setup PostgreSQL database |
|
||||
| `verify-services.ps1` | `verify-services.sh` | Verify all services |
|
||||
| `complete-todos.ps1` | `complete-todos.sh` | Track todo completion |
|
||||
| `consolidate-branches.ps1` | `consolidate-branches.sh` | Consolidate branches |
|
||||
|
||||
## Making Scripts Executable
|
||||
|
||||
After cloning the repository, make all scripts executable:
|
||||
|
||||
```bash
|
||||
# In WSL/Ubuntu terminal
|
||||
cd /mnt/c/Users/intlc/defi_oracle_projects/CurrenciCombo
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Start Development Servers
|
||||
|
||||
```bash
|
||||
# Start webapp and orchestrator
|
||||
./scripts/start-dev.sh
|
||||
|
||||
# Start all services (including database)
|
||||
./scripts/start-all.sh
|
||||
```
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```bash
|
||||
./scripts/check-status.sh
|
||||
```
|
||||
|
||||
### Test API Endpoints
|
||||
|
||||
```bash
|
||||
./scripts/test-curl.sh
|
||||
```
|
||||
|
||||
### Fix Frontend Issues
|
||||
|
||||
```bash
|
||||
./scripts/fix-frontend.sh
|
||||
```
|
||||
|
||||
### Setup Database
|
||||
|
||||
```bash
|
||||
./scripts/setup-database.sh
|
||||
```
|
||||
|
||||
### Verify Services
|
||||
|
||||
```bash
|
||||
./scripts/verify-services.sh
|
||||
```
|
||||
|
||||
## Working with WSL
|
||||
|
||||
### Accessing Windows Files
|
||||
|
||||
WSL mounts Windows drives at `/mnt/c/`, `/mnt/d/`, etc. Your project is likely at:
|
||||
```bash
|
||||
/mnt/c/Users/intlc/defi_oracle_projects/CurrenciCombo
|
||||
```
|
||||
|
||||
### Opening WSL from Windows
|
||||
|
||||
You can open WSL from Windows in several ways:
|
||||
1. Type `wsl` in PowerShell or Command Prompt
|
||||
2. Type `ubuntu` in Windows Start menu
|
||||
3. Use Windows Terminal with WSL profile
|
||||
|
||||
### Opening Windows Explorer from WSL
|
||||
|
||||
```bash
|
||||
# Open current directory in Windows Explorer
|
||||
explorer.exe .
|
||||
```
|
||||
|
||||
### Running Windows Commands from WSL
|
||||
|
||||
```bash
|
||||
# Example: Open a URL in Windows browser
|
||||
cmd.exe /c start http://localhost:3000
|
||||
```
|
||||
|
||||
## Differences from PowerShell
|
||||
|
||||
1. **Path Separators**: Use `/` instead of `\`
|
||||
2. **Script Execution**: Use `./script.sh` instead of `.\script.ps1`
|
||||
3. **Environment Variables**: Use `$VARIABLE` instead of `$env:VARIABLE`
|
||||
4. **Command Chaining**: Use `&&` or `;` instead of `;` in PowerShell
|
||||
5. **Background Processes**: Use `&` at end of command instead of `Start-Process`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Scripts Not Executable
|
||||
|
||||
If you get "Permission denied" errors:
|
||||
```bash
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
If a port is already in use:
|
||||
```bash
|
||||
# Find process using port 3000
|
||||
lsof -ti:3000
|
||||
|
||||
# Kill process
|
||||
kill $(lsof -ti:3000)
|
||||
```
|
||||
|
||||
### Docker Not Accessible
|
||||
|
||||
If Docker commands fail:
|
||||
```bash
|
||||
# Check if Docker daemon is running
|
||||
sudo service docker status
|
||||
|
||||
# Start Docker daemon if needed
|
||||
sudo service docker start
|
||||
|
||||
# Add user to docker group (one-time setup)
|
||||
sudo usermod -aG docker $USER
|
||||
# Then log out and back in
|
||||
```
|
||||
|
||||
### Node.js Not Found
|
||||
|
||||
If Node.js is not found:
|
||||
```bash
|
||||
# Check Node.js version
|
||||
node --version
|
||||
|
||||
# If not installed, use nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install 18
|
||||
nvm use 18
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Make all scripts executable: `chmod +x scripts/*.sh`
|
||||
2. Set up environment variables (see main README)
|
||||
3. Install dependencies: `npm install` in each directory
|
||||
4. Start services: `./scripts/start-all.sh`
|
||||
5. Verify services: `./scripts/check-status.sh`
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)
|
||||
- [Ubuntu on WSL](https://ubuntu.com/wsl)
|
||||
- [Docker Desktop for Windows](https://docs.docker.com/desktop/windows/install/)
|
||||
|
||||
Reference in New Issue
Block a user