fast-deployment/README.md

A lightweight Node.js package for rapid deployment of Vue.js, Next.js, and Nuxt.js applications

# Fast Deployment

A lightweight Node.js package for rapid deployment of Vue.js, Next.js, and Nuxt.js applications.

## Quick Start

1. Install the package in your project:
```bash
npm install --save-dev fast-deployment
```

2. Add the deploy script to your package.json:
```json
{
  "scripts": {
    "deploy": "fast-deployment"
  }
}
```

3. Create a `.env` file in your project root with your deployment configuration:
```env
# Required settings
DEPLOYMENT_SERVER_HOST=yourserver.com
DEPLOYMENT_SERVER_USER=username
DEPLOYMENT_SERVER_DIR=/var/www/yourapp
DEPLOYMENT_FOLDER_NAME=app
DEPLOYMENT_APP_TYPE=vue  # Options: vue, next, nuxt

# Optional settings
DEPLOYMENT_HTACCESS_TEMPLATE=.htaccess.template
DEPLOYMENT_HEALTH_CHECK_URL=http://localhost:3000/api/health
DEPLOYMENT_HEALTH_CHECK_STATUS=200
DEPLOYMENT_PM2_APP_NAME=app-server
```

4. Run the deployment:
```bash
npm run deploy
```

## Step-by-Step Setup Guide

### 1. Installation
First, install the package as a development dependency:
```bash
npm install --save-dev fast-deployment
```

### 2. Configuration Setup

#### 2.1 Add Deploy Script
Manually add the deploy script to your package.json:
```json
{
  "scripts": {
    "deploy": "fast-deployment"
  }
}
```

#### 2.2 Environment Variables
Create a `.env` file in your project root with the following variables:

* Required Settings:
  - `DEPLOYMENT_SERVER_HOST`: Your server's hostname or IP
  - `DEPLOYMENT_SERVER_USER`: SSH username
  - `DEPLOYMENT_SERVER_DIR`: Remote directory path
  - `DEPLOYMENT_FOLDER_NAME`: Name for your deployment folder
  - `DEPLOYMENT_APP_TYPE`: Type of application (vue, next, or nuxt)

* Optional Settings:
  - `DEPLOYMENT_HTACCESS_TEMPLATE`: Path to custom .htaccess template
  - `DEPLOYMENT_HEALTH_CHECK_URL`: URL to verify deployment
  - `DEPLOYMENT_HEALTH_CHECK_STATUS`: Expected health check status code
  - `DEPLOYMENT_PM2_APP_NAME`: PM2 process name (if using PM2)

Example .env file:
```env
DEPLOYMENT_SERVER_HOST=example.com
DEPLOYMENT_SERVER_USER=deploy
DEPLOYMENT_SERVER_DIR=/var/www/myapp
DEPLOYMENT_FOLDER_NAME=myapp
DEPLOYMENT_APP_TYPE=next
DEPLOYMENT_HEALTH_CHECK_URL=https://example.com/api/health
DEPLOYMENT_HEALTH_CHECK_STATUS=200
```

### 3. SSH Setup
Ensure you have SSH access to your server with key-based authentication:

1. If you haven't generated an SSH key:
```bash
ssh-keygen -t rsa -b 4096
```

2. Copy your public key to the server:
```bash
ssh-copy-id username@yourserver.com
```

### 4. Usage

Once setup is complete, you can deploy your application with:
```bash
npm run deploy
```

The deployment process will:
1. Build your application
2. Create a deployment package
3. Upload to your server
4. Set up the new version
5. Update the "current" symlink
6. Run health checks (if configured)

## Example Projects

### Vue.js Project
```env
DEPLOYMENT_SERVER_HOST=vue-app.com
DEPLOYMENT_SERVER_USER=deploy
DEPLOYMENT_SERVER_DIR=/var/www/vue-app
DEPLOYMENT_FOLDER_NAME=vue-app
DEPLOYMENT_APP_TYPE=vue
```

### Next.js Project
```env
DEPLOYMENT_SERVER_HOST=next-app.com
DEPLOYMENT_SERVER_USER=deploy
DEPLOYMENT_SERVER_DIR=/var/www/next-app
DEPLOYMENT_FOLDER_NAME=next-app
DEPLOYMENT_APP_TYPE=next
DEPLOYMENT_PM2_APP_NAME=next-server
```

### Nuxt.js Project
```env
DEPLOYMENT_SERVER_HOST=nuxt-app.com
DEPLOYMENT_SERVER_USER=deploy
DEPLOYMENT_SERVER_DIR=/var/www/nuxt-app
DEPLOYMENT_FOLDER_NAME=nuxt-app
DEPLOYMENT_APP_TYPE=nuxt
DEPLOYMENT_PM2_APP_NAME=nuxt-server
```

## Troubleshooting

### Common Issues

1. **SSH Connection Failed**
   - Verify your SSH key is properly set up
   - Check if you can manually SSH into the server
   - Ensure the DEPLOYMENT_SERVER_USER has proper permissions

2. **Build Failed**
   - Check if the build works locally with `npm run build`
   - Verify all dependencies are installed
   - Check your application type is correctly set in .env

3. **Health Check Failed**
   - Verify the health check URL is accessible
   - Check if the application is properly started
   - Ensure the expected status code is correct

### Debug Logs
The deployment process outputs detailed logs. Look for:
- Build process output
- SSH connection status
- File transfer progress
- Deployment script execution
- Health check results

## License

MIT