remote-deploy-cli 1.0.0 → 1.1.1

package/README.md

@@ -1,119 +1,234 @@
 # redep (Remote Deploy CLI)
 
-A lightweight Node.js CLI tool for remote execution using a Client-Server architecture. Designed to simplify deployment workflows (e.g., triggering Docker Compose on a remote server).
+> A lightweight, secure Node.js CLI tool for remote execution using a Client-Server architecture. Designed to simplify deployment workflows by triggering commands (like Docker Compose) on remote servers securely.
 
-## Features
+![npm version](https://img.shields.io/npm/v/remote-deploy-cli.svg)
+![License](https://img.shields.io/npm/l/remote-deploy-cli.svg)
 
-- **Client-Server Architecture**: Centralized control where Client sends commands and Server executes them.
-- **Secure Communication**: Uses Token-based authentication (Bearer Token) to ensure only authorized clients can execute commands.
-- **Configurable**: Easy configuration management for both Client and Server via CLI or Environment Variables.
-- **Docker Integration**: Built-in support for `deploy fe` which pulls and restarts containers using Docker Compose.
-- **Docker Support**: Can be run as a Docker container itself on the server machine.
-- **Logging**: Detailed logs for tracking execution status.
+**Last Updated:** 2026-01-17
 
-## Architecture
+## Table of Contents
 
-1.  **Client Machine**: The client that issues deployment commands (e.g., your laptop or CI runner).
-2.  **Server Machine**: The server that hosts the application and executes the deployment commands (e.g., `docker compose up`).
+- [Description](#description)
+- [Architecture Overview](#architecture-overview)
+- [Installation](#installation)
+- [Client Commands](#client-commands)
+  - [deploy](#deploy)
+  - [Client Configuration](#client-configuration)
+- [Server Commands](#server-commands)
+  - [listen](#listen)
+  - [start (Background)](#start-background)
+  - [Server Configuration](#server-configuration)
+- [Command Interactions](#command-interactions)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-Communication happens via HTTP/REST with a shared secret for authentication.
+---
+
+## Description
+
+**redep** allows you to securely trigger deployment scripts on a remote server from your local machine or CI/CD pipeline.
+
+## Architecture Overview
+
+1.  **Server (Remote Machine)**: Runs the listener process (`redep listen`). It waits for authenticated HTTP requests and executes local shell commands (e.g., `docker compose up`).
+2.  **Client (Local Machine/CI)**: Sends commands (`redep deploy`) to the Server URL.
+
+---
 
 ## Installation
 
-You can install this package globally using npm:
+### Global Installation (Recommended)
+
+To use `redep` as a command-line tool anywhere on your system:
 
 ```bash
-# Clone the repository
-git clone <repo-url>
-cd remote-deploy-cli
+npm install -g remote-deploy-cli
+```
 
-# Install globally (for development/local use)
-npm install -g .
+### Local Installation
+
+If you prefer to use it within a specific project (e.g., via `npm scripts`):
+
+```bash
+npm install remote-deploy-cli --save-dev
 ```
 
-## Usage
+---
 
-### 1. Configure the Server Machine
+## Client Commands
 
-#### Option A: Running directly on Node.js
+These commands are executed on your **local machine** or **CI/CD runner**.
 
-On the machine where you want to run your application (Server):
+### `deploy`
 
-1.  **Set the Working Directory**: This is where your `docker-compose.yml` is located.
-    ```bash
-    redep config set working_dir /path/to/your/project
-    ```
+Triggers a deployment on the remote server.
 
-2.  **Set a Secret Key**: A secure password for authentication.
-    ```bash
-    redep config set secret_key super-secure-secret-123
-    ```
+**Syntax:**
+```bash
+redep deploy <type>
+```
 
-3.  **Start the Listener**:
-    ```bash
-    redep listen
-    # Optional: Specify port (default 3000)
-    # redep listen --port 4000
-    ```
+**Parameters:**
+- `<type>`: The service type to deploy. Currently supports `fe` (frontend).
 
-#### Option B: Running with Docker (Recommended)
+**Requirements:**
+- `SERVER_URL` must be configured.
+- `SECRET_KEY` must match the server's key.
 
-You can run the server itself inside a Docker container. We provide a `docker-compose.server.yml` as an example.
+**Example:**
+```bash
+# Deploy frontend service
+redep deploy fe
+```
+
+**Expected Output:**
+```
+[INFO] Deploying fe to http://192.168.1.50:3000...
+[SUCCESS] Deployment triggered successfully.
+```
+
+### Client Configuration
 
-1.  **Prerequisites**: Ensure Docker and Docker Compose are installed on the server machine.
-2.  **Run the Server**:
+Configure the client to know where the server is.
 
-    ```bash
-    # Edit docker-compose.server.yml to map your project directory
-    # Then run:
-    docker compose -f docker-compose.server.yml up -d --build
-    ```
+```bash
+# Set Server URL
+redep config set server_url http://<server-ip>:3000
+
+# Set Secret Key
+redep config set secret_key my-secret-key
+```
 
-    **Configuration via `docker-compose.server.yml`**:
-    -   `volumes`:
-        -   `/var/run/docker.sock:/var/run/docker.sock`: Required to allow the server to manage sibling containers.
-        -   `./your-project:/workspace`: Mount your project directory containing `docker-compose.yml` to `/workspace` inside the container.
-    -   `environment`:
-        -   `WORKING_DIR=/workspace`: Must match the container mount path.
-        -   `SECRET_KEY=your-secret-key`: Set the shared secret.
+---
 
-### 2. Configure the Client Machine
+## Server Commands
 
-On your local machine or CI/CD server (Client):
+These commands are executed on the **remote server** (VPS, VM, etc.).
 
-1.  **Set the Server URL**: The address of your server machine.
-    ```bash
-    redep config set server_url http://<server-ip>:3000
-    ```
-    Or use `SERVER_URL` env var.
+### `listen`
 
-2.  **Set the Secret Key**: Must match the key set on the Server.
-    ```bash
-    redep config set secret_key super-secure-secret-123
-    ```
-    Or use `SECRET_KEY` env var.
+Starts the server in the foreground. Useful for debugging or running inside Docker.
 
-### 3. Execute Deployment
+**Syntax:**
+```bash
+redep listen [--port <number>]
+```
 
-To deploy the Frontend (triggers `docker compose up -d` on the server):
+**Options:**
+- `-p, --port`: Specify port (default: 3000).
 
+**Example:**
 ```bash
-redep deploy fe
+redep listen --port 4000
 ```
 
-## Security Best Practices
+### `start` (Background)
+
+Starts the server in background mode (Daemon).
+*   **Auto-PM2**: If `pm2` is installed, it uses PM2 for process management.
+*   **Native Fallback**: If `pm2` is missing, it uses Node.js `child_process` to detach.
+
+**Syntax:**
+```bash
+redep start [--port <number>]
+```
+
+**Related Commands:**
+- `redep stop`: Stops the background server.
+- `redep status`: Checks if the server is running.
+
+**Example:**
+```bash
+redep start
+# [SUCCESS] Server started in background using PM2
+```
+
+### Server Configuration
+
+Configure the runtime environment for the server.
+
+```bash
+# Set Working Directory (Where docker-compose.yml lives)
+redep config set working_dir /path/to/project
+
+# Set Secret Key
+redep config set secret_key my-secret-key
+```
+
+#### Running with Docker (Recommended)
+
+Instead of manual configuration, run the server as a container:
+
+```yaml
+# docker-compose.server.yml
+services:
+  deploy-server:
+    image: remote-deploy-cli
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./my-app:/workspace
+    environment:
+      - WORKING_DIR=/workspace
+      - SECRET_KEY=secure-key
+```
+
+---
+
+## Command Interactions
+
+### Workflow: Deployment
+
+```mermaid
+sequenceDiagram
+    participant Client (CI/Local)
+    participant Server (Remote)
+    
+    Note over Client: User runs "redep deploy fe"
+    Client->>Client: Read Config (URL, Secret)
+    Client->>Server: POST /deploy { type: "fe" } (Auth: Bearer Token)
+    
+    Note over Server: Verify Secret Key
+    alt Invalid Key
+        Server-->>Client: 403 Forbidden
+        Client->>User: Error: Authentication Failed
+    else Valid Key
+        Server->>Server: Execute "docker compose up" in WORKING_DIR
+        Server-->>Client: 200 OK { status: "success" }
+        Client->>User: Success Message
+    end
+```
+
+---
+
+## Configuration Reference
+
+| Config Key    | Env Variable  | Description                                      | Context          |
+| :------------ | :------------ | :----------------------------------------------- | :--------------- |
+| `server_port` | `SERVER_PORT` | Port for the server to listen on (Default: 3000) | **Server**       |
+| `working_dir` | `WORKING_DIR` | Directory to execute commands in                 | **Server**       |
+| `server_url`  | `SERVER_URL`  | URL of the remote `redep` server                 | **Client**       |
+| `secret_key`  | `SECRET_KEY`  | Shared secret for authentication                 | **Both**         |
+
+---
+
+## Troubleshooting
+
+### `Error: "working_dir" is not set`
+- **Context**: Server
+- **Fix**: Run `redep config set working_dir /path` or check `docker-compose.yml` environment.
 
-- **Secret Management**: Ensure your `secret_key` is strong and not committed to version control.
-- **Network Security**: In production, it is recommended to run the Server behind a reverse proxy (like Nginx) with SSL/TLS (HTTPS) to encrypt the traffic, especially since the secret key is sent in the header.
-- **Firewall**: Restrict access to the Server port (default 3000) to only allow IPs from known Client machines.
+### `Connection Refused`
+- **Context**: Client
+- **Fix**: Ensure server is running (`redep status` or `docker ps`) and port 3000 is open.
 
-## Development
+### `403 Forbidden`
+- **Context**: Client
+- **Fix**: Re-check `SECRET_KEY` on both machines. They must match exactly.
 
-- `bin/index.js`: CLI entry point.
-- `lib/server/`: Server and execution logic.
-- `lib/client/`: Client and command logic.
-- `lib/config.js`: Configuration management using `conf`.
+---
 
 ## License
 
-ISC
+ISC © 2026

package/bin/index.js

@@ -2,6 +2,7 @@
 
 import 'dotenv/config';
 import { Command } from 'commander';
+import { spawn } from 'child_process';
 import { logger } from '../lib/logger.js';
 import { getConfig, setConfig, getAllConfig, clearConfig } from '../lib/config.js';
 import { startServer } from '../lib/server/index.js';
@@ -53,21 +54,156 @@ configCommand
 
 program.addCommand(configCommand);
 
+// Background Process Management
+program
+  .command('start')
+  .description('Start the server in background (daemon mode) using PM2 if available')
+  .option('-p, --port <port>', 'Port to listen on')
+  .action((options) => {
+    // Try to use PM2 first
+    try {
+      // Check if PM2 is available via API
+      // We'll use a dynamic import or checking for the pm2 binary in a real scenario
+      // But here we can just try to spawn 'pm2' command
+      
+      const args = ['start', process.argv[1], '--name', 'redep-server', '--', 'listen'];
+      if (options.port) {
+        args.push('--port', options.port);
+      }
+
+      const pm2 = spawn('pm2', args, {
+        stdio: 'inherit',
+        shell: true // Required to find pm2 in PATH
+      });
+
+      pm2.on('error', () => {
+        // Fallback to native spawn if PM2 is not found/fails
+        logger.info('PM2 not found, falling back to native background process...');
+        startNativeBackground(options);
+      });
+
+      pm2.on('close', (code) => {
+        if (code !== 0) {
+           logger.warn('PM2 start failed, falling back to native background process...');
+           startNativeBackground(options);
+        } else {
+           logger.success('Server started in background using PM2');
+        }
+      });
+
+    } catch (e) {
+      startNativeBackground(options);
+    }
+  });
+
+function startNativeBackground(options) {
+    const existingPid = getConfig('server_pid');
+    
+    if (existingPid) {
+      try {
+        process.kill(existingPid, 0);
+        logger.warn(`Server is already running with PID ${existingPid}`);
+        return;
+      } catch (e) {
+        // Process doesn't exist, clear stale PID
+        setConfig('server_pid', null);
+      }
+    }
+
+    const args = ['listen'];
+    if (options.port) {
+      args.push('--port', options.port);
+    }
+
+    const child = spawn(process.argv[0], [process.argv[1], ...args], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true
+    });
+
+    child.unref();
+    setConfig('server_pid', child.pid);
+    logger.success(`Server started in background (native) with PID ${child.pid}`);
+}
+
+program
+  .command('stop')
+  .description('Stop the background server')
+  .action(() => {
+    // Try PM2 stop first
+    const pm2 = spawn('pm2', ['stop', 'redep-server'], { stdio: 'ignore', shell: true });
+    
+    pm2.on('close', (code) => {
+      if (code === 0) {
+        logger.success('Server stopped (PM2)');
+        return;
+      }
+      
+      // Fallback to native stop
+      const pid = getConfig('server_pid');
+      if (!pid) {
+        logger.warn('No active server found.');
+        return;
+      }
+
+      try {
+        process.kill(pid);
+        setConfig('server_pid', null);
+        logger.success(`Server stopped (PID ${pid})`);
+      } catch (e) {
+        if (e.code === 'ESRCH') {
+          logger.warn(`Process ${pid} not found. Cleaning up config.`);
+          setConfig('server_pid', null);
+        } else {
+          logger.error(`Failed to stop server: ${e.message}`);
+        }
+      }
+    });
+  });
+
+program
+  .command('status')
+  .description('Check server status')
+  .action(() => {
+     // Try PM2 status first
+     const pm2 = spawn('pm2', ['describe', 'redep-server'], { stdio: 'inherit', shell: true });
+
+     pm2.on('close', (code) => {
+        if (code !== 0) {
+             // Fallback to native status
+            const pid = getConfig('server_pid');
+            
+            if (!pid) {
+              logger.info('Server is NOT running.');
+              return;
+            }
+
+            try {
+              process.kill(pid, 0);
+              logger.success(`Server is RUNNING (PID ${pid})`);
+            } catch (e) {
+              logger.warn(`Server is NOT running (Stale PID ${pid} found).`);
+              setConfig('server_pid', null);
+            }
+        }
+     });
+  });
+
 // Server Command
 program
   .command('listen')
   .description('Start the server to listen for commands')
   .option('-p, --port <port>', 'Port to listen on', 3000)
   .action((options) => {
-    const port = options.port || process.env.SERVER_PORT || getConfig('server_port') || 3000;
-    const secret = process.env.SECRET_KEY || getConfig('secret_key');
+    const port = options.port || getConfig('server_port') || process.env.SERVER_PORT || 3000;
+    const secret = getConfig('secret_key') || process.env.SECRET_KEY;
     
     if (!secret) {
       logger.warn('Warning: No "secret_key" set in config or SECRET_KEY env var. Communication might be insecure or fail if client requires it.');
       logger.info('Run "redep config set secret_key <your-secret>" or set SECRET_KEY env var.');
     }
 
-    const workingDir = process.env.WORKING_DIR || getConfig('working_dir');
+    const workingDir = getConfig('working_dir') || process.env.WORKING_DIR;
     if (!workingDir) {
       logger.error('Error: "working_dir" is not set. Please set it using "redep config set working_dir <path>" or WORKING_DIR env var.');
       process.exit(1);
@@ -81,8 +217,8 @@ program
   .command('deploy <type>')
   .description('Deploy a service (e.g., "fe") to the server machine')
   .action(async (type) => {
-    const serverUrl = process.env.SERVER_URL || getConfig('server_url');
-    const secret = process.env.SECRET_KEY || getConfig('secret_key');
+    const serverUrl = getConfig('server_url') || process.env.SERVER_URL;
+    const secret = getConfig('secret_key') || process.env.SECRET_KEY;
 
     if (!serverUrl) {
       logger.error('Error: "server_url" is not set. Set SERVER_URL env var or run "redep config set server_url <url>"');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-deploy-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "main": "index.js",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "dotenv": "^17.2.3",
     "express": "^4.18.2",
     "helmet": "^7.1.0",
-    "morgan": "^1.10.0"
+    "morgan": "^1.10.0",
+    "pm2": "^6.0.14"
   }
 }