@deorta-dev/remotly

Remote Deploy Toolkit — Automate deployment of Node.js / NestJS applications to remote servers via SSH.

npm install -g @deorta-dev/remotly
npx @deorta-dev/remotly deploy

Quick Start

# 1. Create configuration
remotly init
ini
# 2. Edit .remotly-config/global.yml with your server details

# 3. Deploy
remotly deploy                    # interactive
remotly deploy --app api          # headless
remotly deploy --parallel         # multiple apps in parallel

Documentation

• Configuration Reference — All YAML parameters explained
• CLI Commands
• Programmatic API
• Plugin System

CLI Commands

| Command | Description | |---------|-------------| | remotly deploy | Deploy applications to remote servers | | remotly list | List available applications | | remotly init | Create global deploy configuration | | remotly init-app <name> | Create per-app configuration | | remotly status | Check status of deployed services | | remotly logs <app> | Fetch logs from a deployed service | | remotly versions <app> | List available deployment versions | | remotly rollback <app> | Rollback to a previous version |

deploy Options

| Flag | Description | Default | |------|-------------|---------| | -a, --app <name> | App to deploy (repeatable) | prompt | | -c, --config <dir> | Config directory | ./.remotly-config | | -p, --parallel | Deploy in parallel | false | | --no-build | Skip build step | false | | --dry-run | Preview without executing | false | | --env-file <path> | Load additional .env file | — |

logs Options

| Flag | Description | Default | |------|-------------|---------| | -n, --lines <number> | Number of log lines | 50 | | -c, --config <dir> | Config directory | ./.remotly-config |

rollback Options

| Flag | Description | Default | |------|-------------|---------| | -v, --version <version> | Specific version to rollback to | previous version | | -c, --config <dir> | Config directory | ./.remotly-config |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All deploys successful | | 1 | At least one deploy failed | | 2 | Configuration error | | 3 | SSH connection error |

Configuration

# .remotly-config/global.yml
global:
  transport:
    type: ssh
    host: "your-server.com"
    port: 22
    username: "deploy"
    privateKeyPath: "~/.ssh/id_rsa"

  nodeVersion: "20"
  installPath: "/opt/services/{appName}"

  # Service manager: "systemd" (default) or "pm2"
  serviceManager: "systemd"

  # Optional: pre-deploy commands
  preDeploy:
    - command: "mkdir -p /var/log/{appName}"
      description: "Create log directory"

  # Optional: system dependencies
  systemDependencies:
    check: true
    apt:
      - libnss3

  # Optional: post-deploy commands
  postDeploy:
    - command: "systemctl reload nginx"
      description: "Reload reverse proxy"

  # Optional: versioning (timestamped releases + rollback)
  versioning:
    enabled: true
    keepReleases: 5

  # Optional: extra files/directories to upload
  extraFiles:
    - source: "scripts/init.sh"
    - source: "config/"
      destination: "/etc/myapp/config/"

  env:
    NODE_ENV: "production"

apps:
  api:
    env:
      PORT: "3000"

Resolution order: Defaults → global → apps[appName] → per-app file → REMOTLY_* env → CLI flags

See CONFIG_SCHEMA.md for the complete parameter reference.

Programmatic API

import { deploy, deployMultiple, dryRun, scanApps, use } from '@deorta-dev/remotly';
import { firstValueFrom } from 'rxjs';

// Deploy a single app
const result = await firstValueFrom(deploy({ appName: 'api' }));
console.log(result.success); // true | false

// Deploy multiple
const results = await firstValueFrom(
  deployMultiple([
    { appName: 'api' },
    { appName: 'worker' },
  ], { parallel: true }),
);

// Preview
const plan = await firstValueFrom(dryRun({ appName: 'api' }));
console.log(plan.steps);

All async operations return RxJS Observables. The only exception is CLI command handlers which use firstValueFrom to bridge Observable → Promise.

Pipeline

| # | Step | Phase | Description | |---|------|-------|-------------| | 1 | pre-deploy-commands | build | Execute pre-deploy commands (local/remote) | | 2 | build | build | Execute build system | | 3 | validate-output | build | Verify output directory | | 4 | connect | transfer | SSH connection | | 5 | ensure-node | transfer | Verify/install Node.js on remote | | 6 | system-dependencies | transfer | Check/install system packages | | 7 | prepare-dir | transfer | Create remote directories (or release dir with versioning) | | 8 | transfer | transfer | Upload built files | | 9 | upload-extra-files | transfer | Upload extra files/directories | | 10 | symlink-current | transfer | Update current symlink (versioning only) | | 11 | install | install | Remote npm install | | 12 | service-install | install | Install service (systemd or PM2) | | 13 | service-start | start | Start/restart service | | 14 | verify | verify | Verify service is active | | 15 | post-deploy-commands | verify | Execute post-deploy commands (local/remote) |

Each phase has onBefore and onAfter hooks that plugins can intercept.

Plugins

import { use } from '@deorta-dev/remotly';
import { nxPlugin } from '@deorta-dev/remotly-plugin-nx';
import { systemdPlugin } from '@deorta-dev/remotly-plugin-systemd';
import { sshPlugin } from '@deorta-dev/remotly-plugin-ssh';

use(nxPlugin());
use(systemdPlugin());
use(sshPlugin());

Official Plugins

| Package | Purpose | |---------|---------| | @deorta-dev/remotly-plugin-nx | NX scanner + builder | | @deorta-dev/remotly-plugin-systemd | systemd service manager | | @deorta-dev/remotly-plugin-ssh | SSH transport | | @deorta-dev/remotly-plugin-pm2 | PM2 service manager | | @deorta-dev/remotly-plugin-docker | Docker deployment |

Creating a Plugin

import type { RemotlyPlugin } from '@deorta-dev/remotly';
import { of } from 'rxjs';

export const myPlugin = (): RemotlyPlugin => ({
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    onAfterBuild: (ctx) => {
      ctx.log('info', `Build completed for ${ctx.appName}`);
      return of(void 0);
    },
  },
  transports: [
    {
      name: 'my-transport',
      transport: { /* ... */ },
    },
  ],
});

PM2 Support

Remotly supports PM2 as an alternative to systemd for process management. Set serviceManager: "pm2" in your config:

global:
  serviceManager: "pm2"

PM2 is auto-installed on the remote server if not present. The pipeline generates an ecosystem.config.js file.

Versioning & Rollback

Enable timestamped releases to support rollback:

global:
  versioning:
    enabled: true
    keepReleases: 5

When versioning is enabled, each deploy creates a timestamped directory under releases/{YYYYMMDDHHmmss}/, and current becomes a symlink to the active release. Old releases beyond keepReleases are automatically cleaned up.

# List all versions
remotly versions api

# Rollback to previous version
remotly rollback api

# Rollback to specific version
remotly rollback api -v 20240711143000

Extra Files

Upload additional files or directories with the deploy:

global:
  extraFiles:
    - source: "scripts/init.sh"              # relative project path
    - source: "config/"
      destination: "/etc/myapp/config/"      # remote destination (optional)

If destination is omitted, the file is uploaded relative to the target installation directory.

Secrets

Placeholders ${VAR_NAME} are resolved by chaining providers:

env:
  DATABASE_URL: "${DB_PASSWORD}"

Order: process.env → .env file → plugin providers (AWS Secrets Manager, Vault, etc.)

Architecture

CLI layer (commander + inquirer + chalk)
    ↓
Core layer (Deployer + PipelineRunner)
    ↓
Scanner → Builder → Transport → ServiceManager → Secrets

Principles:

• Functional programming — no classes, factory functions
• RxJS Observables — no Promises in library code
• No shared state — each deploy is independent
• Plugin-based — everything is extensible

Development

npm run build          # tsup (ESM + CJS + DTS)
npm run dev            # watch mode
npm run typecheck      # tsc --noEmit
npm run lint           # eslint
npm test               # vitest
npm run test:coverage  # with coverage report

License

MIT — @deorta-dev