BSoft Laravel Sync

Deploy Laravel projects directly from VS Code or Cursor using Git-aware file detection, SSH and rsync.

The extension is designed for developers deploying Laravel applications to Linux servers. It uses your existing OpenSSH configuration and never stores SSH passwords, private keys, .env files, or application secrets.

Features

• Laravel project detection
• Git-aware changed file detection
• Preview deployment
• Deploy changed files
• Deploy last commit
• Full deployment
• SSH connection testing
• rsync file transfer
• project-specific excludes
• protected sensitive files
• optional composer install
• optional frontend asset build
• Laravel cache clearing
• optional queue restart
• remote deletion confirmation
• macOS support
• Linux support
• Windows support through WSL

Requirements

macOS

• Git
• OpenSSH
• rsync

macOS normally includes OpenSSH and rsync. Confirm they are available:

git --version
ssh -V
rsync --version

Linux

• Git
• OpenSSH
• rsync

Example install (Debian/Ubuntu):

sudo apt update
sudo apt install -y git openssh-client rsync

Windows 11

Requirements:

• Git
• Windows OpenSSH Client
• WSL
• Ubuntu or another compatible WSL distro
• rsync installed inside WSL

Example:

wsl --install -d Ubuntu

Then inside WSL:

sudo apt update
sudo apt install -y rsync openssh-client

Test:

wsl rsync --version

BSoft Laravel Sync automatically uses WSL rsync on Windows. SSH authentication still uses the Windows OpenSSH client and your Windows SSH keys / ssh-agent. You do not need to copy private keys into WSL.

SSH Setup

Create a host alias in ~/.ssh/config. The extension runs ssh <alias> and never reads this file itself. Prefer SSH keys instead of passwords. For passphrase-protected keys, unlock them with ssh-agent / ssh-add before deploying.

macOS / Linux example

Host example-vps
    HostName 203.0.113.10
    User deploy
    IdentityFile ~/.ssh/id_ed25519

Confirm outside the editor:

ssh example-vps

Windows example

Host example-vps
    HostName 203.0.113.10
    User deploy
    IdentityFile C:\Users\YourUser\.ssh\id_ed25519
    IdentitiesOnly yes

Confirm:

ssh example-vps

Project Configuration

You do not need to create .bsoft-laravel-sync.json by hand.

1. Open your Laravel project folder in VS Code or Cursor.
2. Press Cmd+Shift+P / Ctrl+Shift+P.
3. Run BSoft Laravel Sync: Configure Project.

The wizard asks for deployment name, environment, SSH Host, Remote Path, automation toggles, and optional Excluded Files. Nothing is written until you choose Save Configuration.

That creates or updates .bsoft-laravel-sync.json in the project root. This file is local configuration only and is never uploaded to the Remote Server.

Example .bsoft-laravel-sync.json

{
  "name": "My Laravel Production",
  "environment": "production",
  "sshHost": "example-vps",
  "remotePath": "/home/example/app",
  "autoClearCache": true,
  "autoComposerInstall": true,
  "autoBuildAssets": true,
  "restartQueueAfterDeploy": false,
  "confirmDeletes": true,
  "exclude": [
    "mobile_app/**"
  ]
}

Configuration properties

Project-file values override matching VS Code settings. Forbidden keys (password, APP_KEY, private key fields, and similar) are ignored.

Do not put secrets in this file. Production .env stays on the Remote Server.

Commands

Deployment Flow

1. Detect Laravel project
2. Read configuration
3. Detect Git changes
4. Apply Protected Files and Excluded Files rules
5. Preview
6. Verify SSH
7. Transfer with rsync
8. Run configured Laravel post-deployment actions

Safety

• .env is protected and never uploaded
• private keys and certificate material (*.pem, *.key, *.p12, *.pfx) are protected
• .bsoft-laravel-sync.json is local only and never uploaded
• .git/, .github/, node_modules/, and vendor/ are protected
• remote deletions require confirmation when configured
• production migration commands never run silently
• Full Deploy never uses rsync --delete
• Output Channel logs redact values that look like secrets

Windows / WSL Notes

Windows path conversion is handled internally by the extension.

C:\Projects\my-laravel-app

becomes:

/mnt/c/Projects/my-laravel-app

SSH continues to use Windows OpenSSH and your Windows ssh-agent. WSL is used only for rsync.

Troubleshooting

SSH connection fails

Confirm ssh example-vps works in a terminal without a password prompt. Unlock passphrase-protected keys with ssh-add. Check HostName, User, Port, and host key trust.

rsync not found

• macOS / Linux: Install rsync and ensure it is on PATH.
• Windows: Install rsync inside WSL (sudo apt install rsync) and verify with wsl rsync --version.

WSL missing

Install WSL (wsl --install -d Ubuntu), reboot if prompted, then install rsync inside the distro.

remote path missing

The configured Remote Path does not exist or is not accessible for the SSH user. Create the directory or fix permissions / path spelling.

permission denied

SSH authentication failed in batch mode. Unlock your key with the system agent, or run ssh <host> once in a terminal.

artisan not found

The Remote Path may not be a Laravel application root, or artisan is missing there.

composer failure

Composer may be missing on the Remote Server, or composer.json / lockfile may be inconsistent. Check the Output Channel for details.

npm build failure

Node/npm may be missing on the Remote Server, or the frontend build script failed. Check the Output Channel for details.

License

MIT

Author

BSoft

Website: https://www.bsoft.mk