Napoleonic Political Magnificence

    @madebywild/wild-deploy

    0.0.1 • Public • Published

    NPM RUN WILD

    Table of contents

    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

    Install

    npm i @madebywild/wild-deploy

    DownloadsWeekly Downloads

    1

    Version

    0.0.1

    License

    MIT

    Unpacked Size

    47.9 kB

    Total Files

    21

    Last publish

    Collaborators

    • wilduser
    • stefank_wild
    • goellner