Deployment

pboss includes a built-in deployment system for SSH-based deployments with release management. Deployments are declared in the deploy block of an ecosystem file.

pboss deploy setup#

Initial setup of the remote server — creates the directory structure and clones the repository:

pboss deploy ecosystem.config.json production setup

This creates the following remote directory structure:

/var/www/app/
├── source/
├── releases/
│   ├── 2025-02-11T10-30-00-000Z/
│   └── 2025-02-10T15-45-00-000Z/
├── current -> releases/2025-02-11T10-30-00-000Z/
└── shared/

pboss deploy#

Deploy a new release:

pboss deploy ecosystem.config.json production

The deploy process works as follows:

1. Runs the preDeploy hook locally (e.g. running tests).
2. Connects via SSH to each configured host.
3. Pulls the latest code from the configured ref.
4. Creates a new timestamped release directory.
5. Updates the current symlink to the new release.
6. Runs the postDeploy hook remotely (e.g. installing dependencies and reloading processes).
7. Cleans up old releases, keeping only the 5 most recent.

Multi-host deployment#

Specify an array of hosts to deploy to all of them sequentially:

{
  "host": ["web1.example.com", "web2.example.com", "web3.example.com"]
}

Configuration reference#

SSH access must be key-based — the deploy flow is non-interactive, so there’s no prompt for passwords.