NPM RUN WILD

Table of contents

• Quick-Guide
• Introduction
• Setup
  • Local Setup
  • Server Setup
  • package.json
  • secret.json
  • CMS Configuration
  • .htaccess-Configuration
• Commands
  • Deployment
  • Rollback
  • Shared Folder Synchronisation
• Customise
• Authors

Quick-Guide

If you are already familiar with npm run wild and just need a quick reminder on how to set up a new project, this section is for you:

• Edit secret.json.example to define your server environments and rename to secret.json (this file should never be checked into GIT)
• Edit package.json: Project information (Name, URL, Git-URL)
• Call "npm install" to download necessary node-modules as defined in package.json
• Edit the server specific .htaccess files

Introduction

What is npm run wild?

npm run wild is a set of tools to streamline the deployment of projects based on the wild-next boilerplate.

This tool is used for:

• Deploying the node stuff of the project and start/restart the PM2 instances on the server
• Deploying the CMS (Craft, Statamic) and setting the correct environments on the target server
• Syncing CMS assets between devs

Setup

Local Setup

What do you need to have set up npm run wild?

Fire up your terminal and run this:

nano ~/.ssh/config

add this line:

IdentityFile ~/.ssh/development.pem

Server Setup

CMS (Development, Staging or Production):

• SSH
• SFTP (probably via SSH)
• Apache
• PHP

Node (Development, Staging or Production):

• SSH
• SFTP (probably via SSH)
• node
• PM2

All shell-scripts are based on BASH, other environments are not tested.

package.json

package.json

Add this to your scripts:

    "bump": "node wild/tasks/bump.js",
    "build": "node wild/tasks/build.js",
    "buildCMS": "node wild/tasks/buildCMS.js",
    "deploy": "node wild/tasks/deploy.js",
    "deployCMS": "node wild/tasks/deployCMS.js",
    "s3": "node wild/tasks/s3.js",
    "invalidate": "node wild/tasks/invalidate.js",
    "wild": "node wild/tasks/wild.js"

secret.json

secret.json

The secret.json contains the various servers you want to deploy to. The secret.json won't be committed to GIT (as defined in the .gitignore file), sensitive information should never be committed. Passwords should be set up in SSH keys, as explained above. You need to manually set up your secret.json, use the provided secret.json.example as a starter.

Setup of "secret.json":

{
	"server": {
		"production": {
			"host": "example.com",
			"user": "userName",
			"path": "/var/www/node",
			"hostCMS": "cms.example.com",
			"userCMS": "userName",
			"pathCMS": "/var/www/cms"
		},
		"staging": {
			"host": "example.com",
			"user": "userName",
			"path": "/var/www/node",
			"hostCMS": "cms.example.com",
			"userCMS": "userName",
			"pathCMS": "/var/www/cms"
		},
		"testserver": {
			"host": "example.com",
			"user": "userName",
			"path": "/var/www/node",
			"hostCMS": "cms.example.com",
			"userCMS": "userName",
			"pathCMS": "/var/www/cms"
		},
		"development": {
			"host": "example.com",
			"user": "userName",
			"path": "/var/www/node",
			"hostCMS": "cms.example.com",
			"userCMS": "userName",
			"pathCMS": "/var/www/cms"
		}
	},
	"aws": {
		"accessKeyId": "xxx",
		"secretAccessKey": "xxx"
	}
}

• "server": the deployment system is configured to use four different servers:
  • "production": the live environment
  • "staging": a stating environment on the production server to test in real-life conditions before deploying to live
  • "testing": a testing environment for the quality assurance team
  • "development": a testing server for the development team – also used for syncing assets between dev team

Edit the host, username and path for every server.

CMS Configuration

To make the CMS ready for different environments, edit the .env files:

• .env.production
• .env.staging
• .env.testing
• .env.development

You don´t have to rename them or move them to a different destination. The deployment script takes care of that for you.

.htaccess-Configuration

To fit your needs you have to modify the htaccess files for every target server.

• .htaccess-production
• .htaccess-staging
• .htaccess-testing
• .htaccess-development

Like with the wp-configs before you don´t have to rename or move anything, because the deployment tool takes care of that.

Commands

There is one command to rule them all:

npm run wild

npm run wild starts a prompt in the command line, where you can select what you want to do. Bump, Build, Deploy, Sync for example.

All the commands are available as standalone commands aswell:

Bump (bumps version of package.json and adds a release tag in the git repository)

npm run bump

Build (Builds the node part of the project)

npm run build

Build CMS (Builds the CMS)

npm run buildCMS

Deploy (Deploys the node part of the project)

npm run deploy

Deploy CMS (Deploys the CMS)

npm run deployCMS

Sync Up (Syncs the CMS assets up)

npm run syncUp

Sync Down (Syncs the CMS assets from a server)

npm run syncDown

Deployment

Deployment is probably the most complex task. You're done with your local development and want to deploy to a testing or live server. Make sure everything is committed to GIT (the repository must be clean because it's getting cloned by the deploy mechanism).

After committing everything you should update the version of your project:

npm run bump

Now select which kind of bump you want to do:

• PATCH This patches your project, e.g. your version is raised from 0.0.1 to 0.0.2.
• MINOR This raises the version number by a minor, e.g. from 1.2.1 to 1.3.0.
• MAJOR This raises your major version number, e.g. from 2.4.2 to 3.0.0.

This will automatically tag your project in GIT with the new version number. Based on this we can now build a clean release-version of the project.

Now build the project - behind the scenes Grunt will clone the project to a build folder, execute a lot of commands like npm install, npm run prod and more in the terminal to create a clean build of the project.

npm run  build

Next we can deploy to one of the four servers defined in secret.json:

npm run deploy

Rollback

!!! NOT YET IMPLEMENTED !!!

In case something went wrong there is an easy rollback mechanism:

npm run rollback

You will get prompted on which server the rollback should occur, then the current version will get replaced by the version before. We only change the symlink to the older version.

Shared Folder Synchronisation

In case of there is a CMS installation we don't commit the "assets - uploads - whatever"-folder to GIT. Since we like to keep the uploads synchronized between servers there are two commands to help you:

npm run syncUp

and

npm run syncDown

npm run syncUp rsyncs the local files to the server.

npm run syncDown rsyncs the files from the server to your local machine.

A prompt will ask in each case which server you want the files to be copied from/to.

Customise

Every project is different, this is why you can customize the build, sync, deploy configs based on your needs.

The configs are to be found in ./wild/tasks/configs and are well documented.

Authors

• Stefan Göllner: main author