Pubsy

Publishing/Deployment library for deploying Angular and other stuff.

This library is designed to create a deployment on a remote server using ssh. It switches deployments using symlinks, and supports rollbacks. All configuration is done through yaml files.

It's currently very much a work in process.

Features

It has tasks for many common actions such as:

• Create angular build: ng build [params]
• Create Angular Universal build
• Copying files around locally
• Copy files to remote server (compressed)
• Create symlinks for deployments and settings files/folders
• Rollbacks

All building can be done locally, to avoid your server having to build / minify / etc.

Documentation

Installation

npm i -g pubsy

Basic usage (command line)

# Build and deploy based on `pubsy.yml` in the current folder. 
pubsy build
 
# Build and deploy based on `pubsy-my-environment.yml` in the current folder. 
pubsy -c my-environment build 
 
# Build and deploy based on `/path/to/pubsy.yml`. 
pubsy -c "/path/to/pubsy.yml" build 
 
# Execute task labeled `ngBuild` in `pubsy.yml` 
pubsy run ngbuild
 
# See help output 
pubsy -h

Basic usage (API)

//All params are optional. Same params can be used as for the command line, except for -h and -v.
const params = {
  config: 'my-environment', //Use config `pubsy-my-environment.yml` in the current folder.
  environment: 'local', //User environment definition named 'local' in config file
}
let p = new Pubsy(params);
//To execute a build
p.build();

Environments

Environments contain settings for the local build folders and the remote deploy folders.

If no environment is configured, an empty environment with default settings is assumed. If environments are configured, you should either set one as default, or specify an environment in the command line with the -e flag.

Property	type	default	description
name	string		A name for reference
default	boolean	false	(optional) set to true to make the default environment to deploy to.
buildPath	string	Empty string	(optional) default path that is prefixed with various tasks params (see tasks)
isRemote	boolean	false	(optional) Is this a remote environment? If true, then host and deployPath should be set.
deployPath	string	Empty string	(optional) Path on the remote server where files will be copied to.
host	string	null	(optional) The remote host. Can be IP address or FQDN.
user	string	Current user	(optional) The user on the remote. Default: the current user.
key	string	~/.ssh/id_rsa	(optional) The path to the private key to authenticate with.
keepDeployments	number	10	(optional) The number of previous deployments to keep.

Example

tasks:
[...]
environments:
  - name: local
    buildPath: .build/intermediate/
    deployPath: /var/www/my-app/
    default: true
  - name: remote-prd-1
    buildPath: .build/intermediate/
    isRemote: true
    deployPath: /var/www/my-app/
    host: example.com
    user: thewizard
    key: /home/thewizard/deployment-keys/private.key

Tasks

Every task has a set of properties that exist for all tasks. Tasks also have individual params that make sense for that specific task.

Global params:

Property	type	default	description
name	string		The task name.
description	string	Empty string	(optional) Something to describe what's going to happen.
label	string	null	(optional) Used with the pubsy run [label] command.
enabled	boolean	true	Set to false to skip this task during a build.
params	any	Depends on task	The task specific parameters.

Some tasks are remote tasks. Those are tasks executed over SSH. For them to work, they need the remote settings in the environment to be set.

Echo

Task name: echo

The echo task simply display one or more messages. You can use variables from the environment in your messages by encasing them in %. For example %name% will print the environment name (if available).

This task is a good starting point for how to make your own tasks.

Property	type	default	description
message	string	'Hello Planet!'	(optional) The message you want to send.
messages	string[]	null	(optional) If you want to print mutliple messages, use this one instead.

Example

tasks:
  - name: echo
    description: Multiple messages
    params: 
      messages:
        - Here I am 
        - Alone again
        - I need you now
        - To hold my hand
  - name: echo
    description: Which environment is this?
    params:
      message: "It is %name%. The buildpath is %buildPath%"

Remove files

Task name: rm

BE CAREFUL AS THIS CAN MESS THINGS UP! FILES WILL BE DELETED! (I may or may not had to redo a few tests that wiped my entire repo folder...)

Property	type	default	description
targets	string / string[]		The folders and/or files to rm -rf.
useBuildPath	boolean	true	(optional) When true, it will prepend the targets with the environment buildPath. When true and no buildPath exist, an error will be thrown for safety.

Example

tasks:
  - name: rm
    description: Clear build folder.
    label: clean
    params: 
      targets: .build/*

Copy files (with globbing)

Task name: copy

Copies files from one place to another. Supports globbing. The sources cannot be paths starting with .', ../ or /, because we need to keep the structure to output. To influence the structure you can use cwdSource to change the working directory for the sources.

Property	type	default	description
source	string / string[]		The source files/patterns to copy. Supports globbing.
cwdSource	string	null	(optional) Change working directory for the source files.
exclude	string / string[]	null	(optional) Files / patterns to exclude. Supports globbing.
dest	string		The destination. This will be prepended with the Environment buildPath if available.
flatten	boolean	false	(optional) Don't keep the folder structure.

Example

tasks:
  - name: copy
    description: All possible options
    label: allOptions
    params: 
      cwdSource: test/base/for/source
      source: 
        - assets/subfolder/*
        - assets/testing.md
        - assets/*.txt
      exclude: '**/file.txt'
      cwdDest: test/base/for/output
      dest: subfolder/under/buildpath/
      flatten: true      
  - name: copy
    description: 'Minimal with label'
    label: minimal
    params: 
      source: 'test/assets/**/*'

Zip files

Task name: zip

Creates a compressed zip file.

Property	type	default	description
source	string / string[]		The source files/patterns to zip. Supports globbing.
cwd	string	null	(optional) Change working directory for the source files.
exclude	string / string[]	null	(optional) Files / patterns to exclude. Supports globbing.
dest	string	files.zip	(optional) The destination. This will be prepended with the Environment buildPath if available. Must end in .zip

Example

tasks:
  - name: zip
    description: Compressing files
    label: zipTest
    params: 
      cwd: test/assets
      source: '**/*'
      dest: 'testFiles.zip'

Angular build

Task name: ngBuild

Create an angular build using the ng command line tool.

Property	type	default	description
base	string	/	(optional) The base element (<base href="/">)
cwd	string	Empty string`	(optional) The directory where the angular project is.
dest	string	dist/	(optional) The destination. This will be prepended with the Environment buildPath if available.
configuration	string	null	(optional) The config to use for the build (the --configuration flag of ng build)

Example

  - name: ngBuild
    description: 'Building Angular App'
    params: 
      base: /my-folder/
      dest: .build/ng/public/
      cwd: /path/to/angular/app

Copy to remote

Task name: copyToRemote

Copies files from the local machine place to a remote. Supports globbing. The sources cannot be paths starting with .', ../ or /, because we need to keep the structure to output. To influence the structure you can use cwdSource to change the working directory for the sources.

Requires remote to be configured in environment.

Property	type	default	description
source	string / string[]		The source files/patterns to copy. Supports globbing.
cwdSource	string	null	(optional) Change working directory for the source files.
exclude	string / string[]	null	(optional) Files / patterns to exclude. Supports globbing.
dest	string	Empty string	(optional) The destination. This will be prepended with the Environment deployPath if available.
flatten	boolean	false	(optional) Don't keep the folder structure.

Example

  - name: copyToRemote
    description: All possible options
    label: allOptions
    params: 
      cwdSource: test/base/for/source
      source: 
        - assets/subfolder/*
        - assets/testing.md
        - assets/*.txt
      exclude: '**/file.txt'
      cwdDest: test/base/for/output
      dest: subfolder/under/buildpath/
      flatten: true      
  - name: copyToRemote
    description: 'Minimal'
    params: 
      source: 'test/assets/**/*'

Unzip remote (beta)

Task name: unzipRemote

Unzip a zip file remotely. Note that the zip file should exist remotely already. (Use copyToRemote to make that happen.)

Requires remote to be configured in environment.

Property	type	default	description
source	string		The source zip file.
dest	string	Empty string	(optional) The destination. This will be prepended with the Environment deployPath if available.
removeAfter	boolean	false	(optional) Remove the zip file after extracting.

example

  - name: unzipRemote
    description: Unzip files remotely
    params: 
      source: testFiles.zip
      dest: release-1/
      removeAfter: true

Symlink remote (beta)

Task name: symlinkRemote

Create a symlink on the remote. Will overwrite any existing symlink if it exists. Works for both files and folders.

Requires remote to be configured in environment.

Property	type	default	description
source	string		The target the link should point to.
dest	string		The (path and) name of the link.
cwd	string	null	(optional) The working directory. (Will cd into this dir before creating the symlink.)

Deploy remote

Task name: deployRemote

This task is basically a shorthand for zip, copyToRemote, unzip and symlink.

In the environment.deployPath (remotely) it will create a new folder with a timestamp (e.g. build-2018-12-27-1545907026579). This has the format [Year]-[Month]-[Day]-[Unix timestamp]. This way deployments are sorted by date, there won't be any conflicts (unless you rollout twice in the same millisecond) and it's human readable.

A symlink called current will be created or updated in the deployPath which will point to the latest build.

The oldest build folders will be deleted if there are more than environment.keepDeployments deployments. It's recommended to keep at least 5, so you can rollback if you need to.

Requires remote to be configured in environment.

Property	type	default	description
source	string / string[]		The source files/patterns to deploy. Supports globbing.
cwd	string	null	(optional) Change working directory for the source files.
exclude	string / string[]	null	(optional) Files / patterns to exclude. Supports globbing.

Example

  - name: deployRemote
    description: Deploy to remote
    params: 
      source: '**/*'
      exclude: '.*'
      cwd: 'test/files/'

Rollback remote

Task name: rollbackRemote

Rolling back can be done through a task if you wish, but is more commonly accessible through the command line. When used through the command line no additional settings in the yaml file are necessary. (The remote environment must be set up.)

pubsy rollback # Rollback to 1 deployment earlier

pubsy rollback 3 # Will rollback 3 deployments (if available)

pubsy rollback build-2018-12-27-1545907026579 # Will rollback to deployment build-2018-12-27-1545907026579

This command will rollback to the previous available deployment. This is dependent on there being a previous deployment available. See environment.keepDeployments for more info.

If a deployment is not available, an error will be thrown.

Development

Todo

[ ] Testing of some tasks [ ] Error handling could be improved [ ] A way for custom tasks to be loaded dynamically [ ] Add documentation for npmTask and cloneRemoteTask [ ] Empty command (pubsy) doesn't return anything at all