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.;//To execute a buildp.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