@doop/deploy v0.0.20

@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.

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.

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)

String Templates

Some config options can be templated using ES6 template syntax.

The following variables are available when templating:

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
			},
		},
	},
};