Uploading and Deploying with WSL

This guide should include every problem I ran into, what caused it, and how I fixed it. This will make the guide fully self-contained for deploying Quartz 4 from Windows → Linux cloud using WSL/rsync/SSH.

---

1. Prerequisites

• Windows PC with WSL (Ubuntu) or Git Bash installed

• Node.js + npm installed

• Quartz 4 project (e.g., note-docs/quartz)

• Linux cloud server (Ubuntu/Debian) with:

  • Nginx installed

  • SSH access (ubuntu@blvaine.ddns.net)

  • rsync installed on server

Tools on Windows:

• WSL or Git Bash

• OpenSSH client (Windows built-in)

• Optional: WinSCP for browsing

---

2️. Prepare Linux Server

1. SSH into the server:

ssh ubuntu@blvaine.ddns.net

2. Install rsync (this fixes the rsync: command not found error):

sudo apt update
sudo apt install rsync -y

3. Ensure deploy folder exists:

sudo mkdir -p /var/www/notes/documentations/public
sudo chown -R ubuntu:ubuntu /var/www/notes/documentations/public

---

3️. Prepare SSH Key for WSL/rsync

Problem 1:

Permission denied (publickey)

Cause: SSH key either not loaded or WSL cannot access it.

Solution:

1. Copy Windows key into WSL:

mkdir -p ~/.ssh
cp /mnt/c/Users/R/.ssh/id_ed25519 ~/.ssh/id_ed25519
cp /mnt/c/Users/R/.ssh/id_ed25519.pub ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

2. Start SSH agent and add key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

3. Test connection:

ssh ubuntu@blvaine.ddns.net

✅ Should log in without a password

Note: WinSCP cannot use WSL keys; for WinSCP, point to your Windows key.

---

4️. Convert Windows line endings in scripts

Problem 2:

deploy.sh: line 3: $'\r': command not found

Cause: Script created in Windows (CRLF endings)

Solution:

• In IntelliJ: Change CRLF → LF at bottom-right of editor

• Or in WSL:

sed -i 's/\r$//' deploy.sh

---

5. Install rsync locally in WSL

Problem 3:

rsync: [sender] Failed to exec C:/Windows/System32/OpenSSH/ssh.exe: No such file or directory

Cause: rsync not installed locally or wrong SSH path

Solution:

• Install rsync in WSL:

sudo apt update
sudo apt install rsync -y

• Use WSL’s SSH, not Windows path (/mnt/c/Users/...)

---

6️. Copy SSH key for WSL

Problem 4:

Permissions 0777 for '/mnt/c/Users/R/.ssh/id_ed25519' are too open.
This private key will be ignored.

Cause: SSH key must have strict Linux permissions

Solution: Copy key to WSL home and chmod:

cp /mnt/c/Users/R/.ssh/id_ed25519 ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
ssh-add ~/.ssh/id_ed25519

---

7️. Deploy script issues

Problem 5: Files were appended, not replaced

• Cause: rsync not using --delete → old files remain

Solution: Use rsync with --delete:

rsync -avz --delete public/ ubuntu@blvaine.ddns.net:/var/www/notes/documentations/public/

---

Problem 6: Deployment works but site doesn’t immediately reflect changes

• Cause 1: Browser caching

  • Hard refresh: Ctrl + F5 / Cmd + Shift + R

• Cause 2: Nginx caching

  • Temporarily disable caching headers:

add_header Cache-Control "no-cache, no-store, must-revalidate";
sudo systemctl reload nginx

• Cause 3: Quartz build not run

  • Always run npx quartz build before deploy

---

Problem 7: rsync fails on server

bash: line 1: rsync: command not found

• Cause: rsync missing on server

• Solution: sudo apt install rsync -y on server

---

Problem 8: WinSCP cannot authenticate

• Cause: WinSCP cannot use WSL keys

• Solution: Use Windows key (C:\Users\R\.ssh\id_ed25519) or convert to .ppk using PuTTYgen

---

8️. Final deploy.sh (all-in-one)

#!/bin/bash
SERVER_USER="ubuntu"
SERVER_HOST="blvaine.ddns.net"
REMOTE_DIR="/var/www/notes/documentations/public"
LOCAL_PUBLIC="public"
 
echo "Building Quartz site..."
npx quartz build || { echo "Build failed!"; exit 1; }
echo "Build finished ✅"
 
echo "Testing SSH..."
ssh -o BatchMode=yes "$SERVER_USER@$SERVER_HOST" "echo SSH OK" >/dev/null 2>&1
if [ $? -ne 0 ]; then
    echo "SSH failed. Run: ssh-add ~/.ssh/id_ed25519"; exit 1
fi
echo "SSH OK ✅"
 
echo "Deploying..."
rsync -avz --delete "$LOCAL_PUBLIC"/ "$SERVER_USER@$SERVER_HOST:$REMOTE_DIR/"
 
if [ $? -eq 0 ]; then
    echo "Deployment successful ✅"
else
    echo "Deployment failed ❌"
    exit 1
fi

---

9️. Run deployment

1. In WSL:

cd /mnt/d/CodingFiles/PersonalCoding/GoLang/note-docs/quartz
chmod +x deploy.sh
bash deploy.sh

2. Verify website updates

3. Hard refresh browser with Ctrl + F5

---

10. Optional: One-click deployment

• Create Windows shortcut:

wsl bash /mnt/d/CodingFiles/PersonalCoding/GoLang/note-docs/quartz/deploy.sh

• Double-click → builds + deploys

---

11. Summary of Problems and Fixes

Problem	Cause	Fix
Permission denied (publickey)	SSH key not loaded	Copy key to WSL, chmod 600, ssh-add
$'\r': command not found	CRLF endings in script	Convert to LF in IntelliJ or sed -i 's/\r$//'
rsync not found locally	rsync not installed	sudo apt install rsync -y in WSL
rsync not found remotely	rsync missing on server	sudo apt install rsync -y
Key too open	Linux requires strict permissions	Copy key to WSL home, chmod 600
Files not updating	rsync --delete missing	Add --delete flag
Browser shows old content	Browser caching	Hard refresh Ctrl+F5
Site shows old content	Nginx caching	Add Cache-Control: no-cache, reload Nginx
WinSCP fails	Cannot use WSL key	Use Windows key or .ppk