@Doop/Deploy

All purpose Doop server deployment script.

This project exposes an executable command line script doop-deploy which is used to deploy Doop projects based on their configuration from app.config.deploy.profiles.

Features:

• Simple pull from git + build + restart PM2 deployment process
• Peer deployments of other profiles if required
• Special branch expressions to query + deploy to complex branches
• File date deltas to skip unnecessary package reinstall, build, restart steps
• Automatic handling of PM2 processes and custom names
• Optional branch Semver + version bumping on successful deploy

NOTE: For verbose debugging set the DEBUG=deploy environment variable as per the Debug config.

System-wide config

@Doop/Deploy generally reads from a Doop projects main config object but if the script is installed system-wide it will also check for a ~/.doop-deploy INI file first.

Any keys within this file are merged into the main ENV setup before processing anything else.

An example of using ~/.doop-deploy to specify a directory to change to before trying to read config:

# Change to site directory to read config
DOOP_DEPLOY_BASE=/sites/acme.com

Environment Variables

Environment variables are read from the current shell and the above ~/.doop-deploy file before execution.

| Variable | Type | Description | |-----------------------|----------|-------------------------------------------------------------------| | DOOP_DEPLOY_BASE | String | Set the working direcotry before attempting to read in the config | | DOOP_DEPLOY_PROFILE | String | Profile to deploy if no CLI profile is selected |

Configuration

Configuration is read per-profile from the app.config.deploy.profiles object. Each key is the local ID of the profile with the object following the specification below.

| Config key | Type | Default | Description | |-------------------|----------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------| | id | String | (key) | The key of the object, provided here for the template engine | | enabled | Boolean | true | Whether the profile is directly deployable, if disabled the profile can only be deployed via a peerDeploy | | path | String | (current path) | Change to this root directory before deploying a profile | | script | Array / String | | Script or other executable which will be run instead of any of the below processes | | repo | String | --repo=<REPO> or "origin" | Which source repository to use when deploying, --repo overrides the setting if present | | branch | String | --branch=<BRANCH> or "master" | The branch to use when deploying, can be a complex expression - see Branch Expressions | | title | String | (key via _.startCase) | The human readable name of the deployment profile | | sort | Number | 10 | Sort position if deploying multiple profiles (low-to-high) | | peerDeploy | Array / String | "" | Additional deployments implied if this profile is deployed | | peerDeny | Array / String | "" | Deployments that are not allowed alongside this profile - an error is raised if both are attempted at once | | processes | Number | 1 | The number of PM2 processes to manage during a deployment | | env | Object | {} | Environment variables to set when building (usually NODE_ENV needs to be set | | semver | Boolean / String | false | Whether to commit a new version completion, ENUM: 'patch' / true, 'minor', 'major' | | semverPackage | Boolean | true | Whether to also bump the new version in package.json | | pm2Name | String | "${profile.id}-${process.alpha}" | Templatable name of the PM2 processes | | pm2Names | Array<String> | (Computed from pm2Name if not specified) | Computed templatable names or manual overrides if needed | | pm2Args | Object<Array> | {} | Specific PM2 arguments per computed instance name | | pm2Args.default | Array | ['-e', (key)] | Universal defaults for PM2 process arguments if no other key matches |

Notes:

• Profiles are always deployed according to sort order, even if specified by peerDeploy
• Setting semver requires write access as it will try to commit the new version based on the result of the deployment (cherry-picks and all)
• If script is specified it is deferred to instead of any other deploy process - no fetching, building or restarts are performed - only the script is run
• When using script only the path and env settings are processed - all other settings are ignored

Branch expressions

The branch property can be set to either:

• A branch name (e.g. 'master', 'dev')
• A tag (e.g. 'v1.2.3')
• A patch hash (e.g. '36d050e', 'f9748544f569e38646a10e8aeecdd0fa47bba0ac')
• One of the special expressions below

The following branch expressions are also supported, they take the form TYPE ARG1=VAL1,ARG2=VAL2,ARG3=VAL3 (e.g. branch: tag semver=v1.x.x,sort=desc)

| Branch type | Arguments | Default | Description | |-------------|-----------|----------|---------------------------------------------------------------------------| | tag | semver | "*" | A semver expression to filter tags by, the first valid semver tag is used | | | sort | "desc" | Whether to sort tags asending, decending before filtering |

String Templates

Some config options can be templated using ES6 template syntax.

The following variables are available when templating:

| Variable | Type | Description | |------------------|----------|---------------------------------------------------------| | _ | Object | Lodash instance | | semver | Object | Semver instance | | profile | Object | Profile configuration object (see above for details) | | process | Object | Details about the current proceses iteration | | process.offset | Number | Offset (starting at zero) of the current iteration | | process.alpha | String | Alphabetical offset of the process (e.g. 'a', 'b' etc.) | | process.name | String | Computed process name |

Example config

Project config

The following is a recommended setup in package.json:

{
  "name": "acme-project",
  "version": "1.0.0",
  "description": "Project that does stuff",
  "main": "server/index.js",
  "scripts": {
    "build": "gulp build",
    "dev": "gulp serve",
    "deploy": "doop-deploy",
    "deploy:pre": "gulp preDeploy",
    "deploy:post": "gulp postDeploy",
    "start": "node server"
  }
}

Basic config

The following is a standard deployment setup with a "Dev" and "Live" profile located in two different paths.

# Within in a Doop `config/index.js` file:
var config = {
	deploy: {
		profiles: {
			dev: {
				title: 'Dev',
				path: '/sites/dev.acme.com',
				sort: 1,
				processes: 2,
				env: {'NODE_ENV': 'dev'},
				pm2Name: 'dev-${process.alpha}',
				pm2Args: {
					default: [
						'-e', 'dev',
						'-o', 'port=${10000 + process.offset + 1}',
						'-o', 'papertrail-program=${process.name}',
					],
					'dev-a': [
						'-e', 'dev',
						'-o', 'port=${10000 + process.offset + 1}',
						'-o', 'papertrail-program=${process.name}',
						'-o', 'cache.cleanAuto=true',
						'-o', 'mongo.migration=true',
					],
				},
			},
			live: {
				title: 'Live',
				path: '/sites/acme.com',
				sort: 2,
				processes: 8,
				env: {'NODE_ENV': 'production'},
				pm2Name: 'live-${process.alpha}',
				pm2Args: {
					default: [
						'-e', 'production',
						'-o', 'port=${10100 + process.offset + 1}',
						'-o', 'papertrail-program=${process.name}',
					],
					'live-a': [
						'-e', 'production',
						'-o', 'port=${10000 + process.offset + 1}',
						'-o', 'papertrail-program=${process.name}',
						'-o', 'cache.cleanAuto=true',
						'-o', 'mongo.migration=true',
					],
				},
			},
		},
	},
}

Chain deployments

The following is an example where:

• Dev becomes the latest version (on npm run deploy --dev)
• Live becomes the Dev version on deploy (on npm run deploy --live)
• Fallback is always the previously deployed live version
• Any deployment to Dev is incremented as a patch on semver, if live is deployed it uses the latest semver

The config below should be spliced into the existing config profile:

var config = {
	deploy: {
		profiles: {
			dev: {
				semver: 'patch', // Increment semver when deploying Dev
			},
			live: {
				peerDeploy: ['dev', 'fallback'], //  Imply other profiles must be updated first
			},
			fallback: {
				enabled: false, // Disable direct deployment
			},
		},
	},
};