{"id":22428478,"url":"https://github.com/momsfriendlydevco/doop-deploy","last_synced_at":"2025-03-27T06:43:54.770Z","repository":{"id":45823223,"uuid":"372640365","full_name":"MomsFriendlyDevCo/doop-deploy","owner":"MomsFriendlyDevCo","description":"All purpose Doop server deployment script","archived":false,"fork":false,"pushed_at":"2022-11-30T00:36:10.000Z","size":235,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-22T15:50:17.518Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MomsFriendlyDevCo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-31T22:15:09.000Z","updated_at":"2021-10-01T02:31:17.000Z","dependencies_parsed_at":"2023-01-22T01:00:58.361Z","dependency_job_id":null,"html_url":"https://github.com/MomsFriendlyDevCo/doop-deploy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MomsFriendlyDevCo%2Fdoop-deploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MomsFriendlyDevCo%2Fdoop-deploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MomsFriendlyDevCo%2Fdoop-deploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MomsFriendlyDevCo%2Fdoop-deploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MomsFriendlyDevCo","download_url":"https://codeload.github.com/MomsFriendlyDevCo/doop-deploy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245798538,"owners_count":20673901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T20:14:56.174Z","updated_at":"2025-03-27T06:43:54.749Z","avatar_url":"https://github.com/MomsFriendlyDevCo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"@Doop/Deploy\n============\nAll purpose Doop server deployment script.\n\nThis project exposes an executable command line script `doop-deploy` which is used to deploy [Doop](https://github.com/MomsFriendlyDevCo/Doop) projects based on their configuration from `app.config.deploy.profiles`.\n\n**Features**:\n\n* Simple pull from git + build + restart PM2 deployment process\n* Peer deployments of other profiles if required\n* Special branch expressions to query + deploy to complex branches\n* File date deltas to skip unnecessary package reinstall, build, restart steps\n* Automatic handling of PM2 processes and custom names\n* Optional branch Semver + version bumping on successful deploy\n\n\nNOTE: For verbose debugging set the `DEBUG=deploy` environment variable as per the [Debug](https://github.com/debug-js/debug) config.\n\n\nSystem-wide config\n------------------\n@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.\n\nAny keys within this file are merged into the main ENV setup before processing anything else.\n\nAn example of using `~/.doop-deploy` to specify a directory to change to before trying to read config:\n\n\n```\n# Change to site directory to read config\nDOOP_DEPLOY_BASE=/sites/acme.com\n```\n\n\nEnvironment Variables\n---------------------\nEnvironment variables are read from the current shell and the above `~/.doop-deploy` file before execution.\n\n\n| Variable              | Type     | Description                                                       |\n|-----------------------|----------|-------------------------------------------------------------------|\n| `DOOP_DEPLOY_BASE`    | `String` | Set the working direcotry before attempting to read in the config |\n| `DOOP_DEPLOY_PROFILE` | `String` | Profile to deploy if no CLI profile is selected                   |\n\n\n\nConfiguration\n-------------\nConfiguration 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.\n\n| Config key        | Type                 | Default                                  | Description                                                                                                 |\n|-------------------|----------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------|\n| `id`              | `String`             | (key)                                    | The key of the object, provided here for the template engine                                                |\n| `enabled`         | `Boolean`            | `true`                                   | Whether the profile is directly deployable, if disabled the profile can only be deployed via a `peerDeploy` |\n| `path`            | `String`             | (current path)                           | Change to this root directory before deploying a profile                                                    |\n| `script`          | `Array` / `String`   |                                          | Script or other executable which will be run instead of any of the below processes                          |\n| `repo`            | `String`             | `--repo=\u003cREPO\u003e` or `\"origin\"`            | Which source repository to use when deploying, `--repo` overrides the setting if present                    |\n| `branch`          | `String`             | `--branch=\u003cBRANCH\u003e` or `\"master\"`        | The branch to use when deploying, can be a complex expression - see Branch Expressions                      |\n| `title`           | `String`             | (key via _.startCase)                    | The human readable name of the deployment profile                                                           |\n| `sort`            | `Number`             | `10`                                     | Sort position if deploying multiple profiles (low-to-high)                                                  |\n| `peerDeploy`      | `Array` / `String`   | `\"\"`                                     | Additional deployments implied if this profile is deployed                                                  |\n| `peerDeny`        | `Array` / `String`   | `\"\"`                                     | Deployments that are not allowed alongside this profile - an error is raised if both are attempted at once  |\n| `processes`       | `Number`             | `1`                                      | The number of PM2 processes to manage during a deployment                                                   |\n| `env`             | `Object`             | `{}`                                     | Environment variables to set when building (usually `NODE_ENV` needs to be set                              |\n| `semver`          | `Boolean` / `String` | `false`                                  | Whether to commit a new version completion, ENUM: 'patch' / `true`, 'minor', 'major'                        |\n| `semverPackage`   | `Boolean`            | `true`                                   | Whether to also bump the new version in `package.json`                                                      |\n| `pm2Name`         | `String`             | `\"${profile.id}-${process.alpha}\"`       | Templatable name of the PM2 processes                                                                       |\n| `pm2Names`        | `Array\u003cString\u003e`      | (Computed from pm2Name if not specified) | Computed templatable names or manual overrides if needed                                                    |\n| `pm2Args`         | `Object\u003cArray\u003e`      | `{}`                                     | Specific PM2 arguments per computed instance name                                                           |\n| `pm2Args.default` | `Array`              | `['-e', (key)]`                          | Universal defaults for PM2 process arguments if no other key matches                                        |\n\n\n**Notes:**\n* Profiles are always deployed according to `sort` order, even if specified by `peerDeploy`\n* 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)\n* 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\n* When using `script` only the `path` and `env` settings are processed - all other settings are ignored\n\n\nBranch expressions\n------------------\nThe `branch` property can be set to either:\n* A branch name (e.g. 'master', 'dev')\n* A tag (e.g. 'v1.2.3')\n* A patch hash (e.g. '36d050e', 'f9748544f569e38646a10e8aeecdd0fa47bba0ac')\n* One of the special expressions below\n\nThe 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`)\n\n| Branch type | Arguments | Default  | Description                                                               |\n|-------------|-----------|----------|---------------------------------------------------------------------------|\n| `tag`       | `semver`  | `\"*\"`    | A semver expression to filter tags by, the first valid semver tag is used |\n|             | `sort`    | `\"desc\"` | Whether to sort tags asending, decending before filtering                 |\n\n\nString Templates\n----------------\nSome config options can be templated using [ES6 template syntax](https://github.com/MomsFriendlyDevCo/template).\n\nThe following variables are available when templating:\n\n| Variable         | Type     | Description                                             |\n|------------------|----------|---------------------------------------------------------|\n| `_`              | `Object` | Lodash instance                                         |\n| `semver`         | `Object` | Semver instance                                         |\n| `profile`        | `Object` | Profile configuration object (see above for details)    |\n| `process`        | `Object` | Details about the current proceses iteration            |\n| `process.offset` | `Number` | Offset (starting at zero) of the current iteration      |\n| `process.alpha`  | `String` | Alphabetical offset of the process (e.g. 'a', 'b' etc.) |\n| `process.name`   | `String` | Computed process name                                   |\n\n\nExample config\n==============\n\nProject config\n--------------\nThe following is a recommended setup in `package.json`:\n\n\n```json\n{\n  \"name\": \"acme-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Project that does stuff\",\n  \"main\": \"server/index.js\",\n  \"scripts\": {\n    \"build\": \"gulp build\",\n    \"dev\": \"gulp serve\",\n    \"deploy\": \"doop-deploy\",\n    \"deploy:pre\": \"gulp preDeploy\",\n    \"deploy:post\": \"gulp postDeploy\",\n    \"start\": \"node server\"\n  }\n}\n```\n\n\n\nBasic config\n------------\n\nThe following is a standard deployment setup with a \"Dev\" and \"Live\" profile located in two different paths.\n\n```javascript\n# Within in a Doop `config/index.js` file:\nvar config = {\n\tdeploy: {\n\t\tprofiles: {\n\t\t\tdev: {\n\t\t\t\ttitle: 'Dev',\n\t\t\t\tpath: '/sites/dev.acme.com',\n\t\t\t\tsort: 1,\n\t\t\t\tprocesses: 2,\n\t\t\t\tenv: {'NODE_ENV': 'dev'},\n\t\t\t\tpm2Name: 'dev-${process.alpha}',\n\t\t\t\tpm2Args: {\n\t\t\t\t\tdefault: [\n\t\t\t\t\t\t'-e', 'dev',\n\t\t\t\t\t\t'-o', 'port=${10000 + process.offset + 1}',\n\t\t\t\t\t\t'-o', 'papertrail-program=${process.name}',\n\t\t\t\t\t],\n\t\t\t\t\t'dev-a': [\n\t\t\t\t\t\t'-e', 'dev',\n\t\t\t\t\t\t'-o', 'port=${10000 + process.offset + 1}',\n\t\t\t\t\t\t'-o', 'papertrail-program=${process.name}',\n\t\t\t\t\t\t'-o', 'cache.cleanAuto=true',\n\t\t\t\t\t\t'-o', 'mongo.migration=true',\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t},\n\t\t\tlive: {\n\t\t\t\ttitle: 'Live',\n\t\t\t\tpath: '/sites/acme.com',\n\t\t\t\tsort: 2,\n\t\t\t\tprocesses: 8,\n\t\t\t\tenv: {'NODE_ENV': 'production'},\n\t\t\t\tpm2Name: 'live-${process.alpha}',\n\t\t\t\tpm2Args: {\n\t\t\t\t\tdefault: [\n\t\t\t\t\t\t'-e', 'production',\n\t\t\t\t\t\t'-o', 'port=${10100 + process.offset + 1}',\n\t\t\t\t\t\t'-o', 'papertrail-program=${process.name}',\n\t\t\t\t\t],\n\t\t\t\t\t'live-a': [\n\t\t\t\t\t\t'-e', 'production',\n\t\t\t\t\t\t'-o', 'port=${10000 + process.offset + 1}',\n\t\t\t\t\t\t'-o', 'papertrail-program=${process.name}',\n\t\t\t\t\t\t'-o', 'cache.cleanAuto=true',\n\t\t\t\t\t\t'-o', 'mongo.migration=true',\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t},\n}\n```\n\n\nChain deployments\n-----------------\nThe following is an example where:\n* Dev becomes the latest version (on `npm run deploy --dev`)\n* Live becomes the Dev version on deploy (on `npm run deploy --live`)\n* Fallback is always the previously deployed live version\n* Any deployment to Dev is incremented as a patch on semver, if live is deployed it uses the latest semver\n\nThe config below should be spliced into the existing config profile:\n\n```javascript\nvar config = {\n\tdeploy: {\n\t\tprofiles: {\n\t\t\tdev: {\n\t\t\t\tsemver: 'patch', // Increment semver when deploying Dev\n\t\t\t},\n\t\t\tlive: {\n\t\t\t\tpeerDeploy: ['dev', 'fallback'], //  Imply other profiles must be updated first\n\t\t\t},\n\t\t\tfallback: {\n\t\t\t\tenabled: false, // Disable direct deployment\n\t\t\t},\n\t\t},\n\t},\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmomsfriendlydevco%2Fdoop-deploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmomsfriendlydevco%2Fdoop-deploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmomsfriendlydevco%2Fdoop-deploy/lists"}