228 lines
6.9 KiB
Markdown
228 lines
6.9 KiB
Markdown
# MTC Project Sync Script
|
|
|
|
A simple toolkit for synchronizing projects between remote servers and local development environments.
|
|
|
|
## Setup
|
|
|
|
### 1. Clone the Repository
|
|
|
|
```bash
|
|
cd ~/Documents/GitHub
|
|
git clone <repository-url> mtc-project-sync-script
|
|
```
|
|
|
|
### 2. Create a Symlink in Your Projects Directory
|
|
|
|
Navigate to where you keep all your projects and create a symbolic link to the sync script:
|
|
|
|
```bash
|
|
cd ~/Documents/Projects # or wherever you keep your projects
|
|
ln -s ~/Documents/GitHub/mtc-project-sync-script/sync-project.sh sync-project.sh
|
|
```
|
|
|
|
**Why symlink?** The script uses its own location to find the `scripts/` folder and `lazygit` binary. A symlink preserves the connection to the original script location, so it can access these resources. This way, you only need one copy of the toolkit that all your projects can use.
|
|
|
|
### 3. Run the Sync Script
|
|
|
|
From your projects directory, run:
|
|
|
|
```bash
|
|
./sync-project.sh
|
|
```
|
|
|
|
**Available flags:**
|
|
|
|
```bash
|
|
./sync-project.sh -h # Show help manual
|
|
./sync-project.sh --files-only # Quick sync (files only, no scripts)
|
|
./sync-project.sh --sftp-only # SFTP setup (no lazygit, no .gitignore updates)
|
|
./sync-project.sh --git # Full project setup via git clone
|
|
```
|
|
|
|
## What the Script Does
|
|
|
|
When you run `sync-project.sh`, it will:
|
|
|
|
1. **Ask for configuration:**
|
|
- Server user@host (e.g., `user@example.com`)
|
|
- SSH password
|
|
- Server project path (defaults to `~/public_leo`, supports `~` paths)
|
|
- Local folder path (e.g., `my-project`)
|
|
|
|
2. **Prepare the connection:**
|
|
- Auto-accepts new server host keys (first-time connections work seamlessly)
|
|
- Resolves `~` paths to full paths via SSH
|
|
- Syncs terminal info for ghostty/kitty terminals (full sync only)
|
|
|
|
3. **Sync your project:**
|
|
- Creates a tar archive on the remote server
|
|
- Downloads and extracts it to your local folder
|
|
- Cleans up temporary files
|
|
|
|
4. **Generate configuration and scripts:**
|
|
- Creates `.vscode/sftp.json` for VS Code SFTP extension
|
|
- Generates helper scripts with your credentials pre-configured
|
|
- Adds scripts to `.gitignore` (unless using `--sftp-only`)
|
|
- Uploads lazygit to server (unless using `--sftp-only`)
|
|
|
|
## Generated Scripts
|
|
|
|
After running the sync script, you'll have these helper scripts in your project:
|
|
|
|
### `remote-local.sh`
|
|
**Purpose:** Download files from server to local machine
|
|
|
|
**What it does:**
|
|
- Uses rsync to pull files from remote server
|
|
- Only downloads changed files
|
|
- Excludes common development folders (node_modules, vendor, .git, etc.)
|
|
|
|
**Use cases:**
|
|
- Get latest changes from server
|
|
- Pull production data for debugging
|
|
- Sync before starting work
|
|
|
|
### `local-remote.sh`
|
|
**Purpose:** Upload files from local machine to server
|
|
|
|
**What it does:**
|
|
- Uses rsync to push files to remote server
|
|
- Only uploads changed files
|
|
- Deletes remote files that don't exist locally
|
|
- Excludes common development folders
|
|
|
|
**Use cases:**
|
|
- Deploy local changes to server
|
|
- Push code updates
|
|
- Restore server from local backup
|
|
|
|
### `ssh.sh`
|
|
**Purpose:** SSH into the remote server
|
|
|
|
**What it does:**
|
|
- Opens an SSH connection to your server
|
|
- Changes directory to your project path
|
|
- Multiple operation modes via flags
|
|
|
|
**Usage:**
|
|
```bash
|
|
./ssh.sh # Normal SSH connection
|
|
./ssh.sh --db # SSH with MySQL port forwarding (local:3306 -> remote:3306)
|
|
./ssh.sh --git # Launch lazygit on server, sync changes back when done
|
|
./ssh.sh --todo # Search for TODO markers in project files
|
|
```
|
|
|
|
**Use cases:**
|
|
- Run commands on the server
|
|
- Check logs
|
|
- Access remote database via localhost:3306
|
|
- Git operations via lazygit
|
|
|
|
### `sftp-watch.sh`
|
|
**Purpose:** Continuous bidirectional sync
|
|
|
|
**What it does:**
|
|
- First runs `remote-local.sh` to sync down
|
|
- Watches for local file changes
|
|
- Automatically runs `local-remote.sh` when files change
|
|
|
|
**Requirements:** Needs `watchexec` installed (`brew install watchexec`)
|
|
|
|
**Use cases:**
|
|
- Development with live server testing
|
|
- Real-time sync during coding
|
|
|
|
### `watch-build.sh`
|
|
**Purpose:** Watch for changes, build, and upload
|
|
|
|
**What it does:**
|
|
- Monitors files for changes
|
|
- Runs `npm run build` when changes detected
|
|
- Uploads built assets to server using `local-remote.sh`
|
|
|
|
**Requirements:**
|
|
- `watchexec` installed
|
|
- `package.json` with build script
|
|
- Node.js/npm installed
|
|
|
|
**Use cases:**
|
|
- Frontend development with build steps (React, Vue, etc.)
|
|
- Automatic deployment of compiled assets
|
|
- Continuous integration during development
|
|
|
|
## Sync Modes
|
|
|
|
### Default Mode
|
|
Full setup with all features:
|
|
- Syncs terminal info (xterm-ghostty or xterm-kitty)
|
|
- Downloads all project files
|
|
- Creates `.vscode/sftp.json`
|
|
- Generates all helper scripts
|
|
- Uploads lazygit to server
|
|
- Updates `.gitignore`
|
|
|
|
### `--git` Mode
|
|
Full project setup via git clone with comprehensive environment configuration:
|
|
|
|
**What it does (12 steps):**
|
|
1. **Clone repository** via git over SSH, check for `.npmrc`
|
|
2. **Copy Docker env** from `.docker/config/.env.local` to `.env`
|
|
3. **Clean Docker** - stop/remove all containers and volumes
|
|
4. **Run docker-setup.sh** if present
|
|
5. **Copy server .env** to `.server.env` (marked assume-unchanged)
|
|
6. **Modify local .env** - extract APP_NAME and APP_KEY from server
|
|
7. **Create .env.prod.local** with production database credentials
|
|
8. **Add helper scripts** - generates `ssh.sh` with embedded credentials
|
|
9. **Upload lazygit** to server (marked assume-unchanged)
|
|
10. **SSH key management** - generates or downloads `staging.key`
|
|
11. **SSH-add** - adds staging.key to SSH agent
|
|
12. **Database setup** - runs `db:wipe` and `make db-sync`
|
|
|
|
**Generated files:**
|
|
- `ssh.sh` - SSH helper script (added to .gitignore)
|
|
- `staging.key` - SSH private key for server access (added to .gitignore)
|
|
- `.server.env` - Copy of server's .env file
|
|
- `.env.prod.local` - Production credentials for database sync
|
|
|
|
**Use cases:**
|
|
- Setting up a new development environment from scratch
|
|
- Cloning a project with full Docker and database configuration
|
|
- Projects that use git for version control on the server
|
|
|
|
### `--files-only` Mode
|
|
Quick sync for when you just need the files:
|
|
- Downloads project files (excludes `node_modules`, `vendor`)
|
|
- No helper scripts generated
|
|
- No configuration files created
|
|
- No lazygit upload
|
|
|
|
### `--sftp-only` Mode
|
|
Lightweight setup for SFTP workflows:
|
|
- Downloads all project files
|
|
- Creates `.vscode/sftp.json`
|
|
- Generates: `local-remote.sh`, `remote-local.sh`, `sftp-watch.sh`, `ssh.sh`
|
|
- No lazygit upload
|
|
- No `.gitignore` modifications
|
|
|
|
## Requirements
|
|
|
|
- **bash** - Shell scripting
|
|
- **ssh/scp** - Remote server access
|
|
- **sshpass** - Password authentication
|
|
- **tar** - Archive creation
|
|
- **rsync** - File synchronization
|
|
- **git** - For `--git` mode
|
|
- **docker** - For `--git` mode
|
|
- **make** - For `--git` mode database sync
|
|
- **watchexec** (optional) - For watch mode scripts
|
|
|
|
### Install on macOS:
|
|
```bash
|
|
brew install sshpass rsync watchexec
|
|
```
|
|
|
|
### Install on Ubuntu/Debian:
|
|
```bash
|
|
sudo apt-get install sshpass rsync openssh-client
|
|
```
|