exp-containership

    0.3.14 • Public • Published

    exp-containership

    Build and deploy applications as containers.

    Newcomers, start here please:

    Problems look at issues

    Configuration

    All configuration of exp-containership is done right inside your package.json. There are sensible defaults for everything so you dont have to specify a config unless you have special needs.

    The following configuration options can be set in package.json under config.exp-containership:

    Option Default Description
    repo exp-docker.repo.dex.nu Docker repository address
    salt https://salt-api.service.consul.xpr.dex.nu Salt API address
    ca embedded ca Path to the CA certificate (PEM format) to use as validation
    insecure false Whether to skip CA certificate validation
    eauth ldap The Salt eauth type, typically pam or ldap
    nojobmerge false Whether to merge or overwrite the default helios job config
    environments.[env].helios_deployment_group [npm_package_name]-[environment] (for example nodefish-production) Helios deployment group to use per environment.
    size small Size of the deployment group, must be one of "small", "medium", "large" or "xlarge".

    Example:

    "config"{
      "exp-containership": {
        "repo": "custom-repo.com",
        "environments": {
          "production": {
             "helios_deployment_group": "custom-deploymentgroup",
             "size": "medium"
          }
        }
      }
    }

    Adding npm scripts

    Add entries to the scripts section to define your exp-containership tasks.

    "scripts"{
      "xpr:init": "exp-containership init",
      "xpr:reset": "exp-containership reset",
      "xpr:build": "exp-containership build",
      "xpr:start": "exp-containership run",
      "xpr:push": "exp-containership push",
      "prexpr:push": "exp-ensure-unmodified && exp-ensure-master && exp-ensure-container-tests",
      "xpr:jobs": "exp-containerdeploy jobs -e",
      "xpr:status": "exp-containerdeploy status -e",
      "xpr:deploy": "exp-containerdeploy deploy -e",
      "xpr:restart": "exp-containerdeploy restart",
      "prexpr:deploy": "exp-ensure-unmodified && exp-ensure-master && exp-ensure-container-tests",
      "xpr:undeploy": "exp-containerdeploy undeploy -e",
      "xpr:init-deployment": "exp-containerdeploy init-deployment -e",
      "xpr:open": "exp-containership open",
      "xpr:test": "exp-containership test",
      "xpr:shell": "exp-containership exec web bash",
      "xpr:logs": "exp-logs",
      "xpr:unpublished-changes": "unpublished-changes"
    }

    Custom pm2 config (optional)

    If the pm2 config shipped with the base image (found here and here) does not suit your needs, you can specify your own. Add two files called config/dev_app.json and config/app.json to your application. The former will be used as pm2 config when running your app on your local development machine, the latter will be used in all other environments ("livedata", "production" etc).

    You then overwrite the original pm2 config by adding the following line where you prefer in your Dockerfile:

    ADD config/*app.json /exp-container/exec/
    

    Helios job file (optional)

    If you require greater control over Helios you can also define helios_jobfile to point to a custom Helios job file for your app. The job file will be merged with the default job file to produce the final version which is sent to Helios.

    Let's say you wanted to enable Varnish.

    1. Specify your job file in package.json
    "config"{
      "exp-containership": {
        "environments": {
          "production": {
            "helios_jobfile": "config/production-job.json"
          }
        }
      }
    }
    1. Add the difference to the specified job file
    {
      "env" : {
        "VARNISH_ENABLED": true
      }
    }
    1. The final job file will now be the default but with VARNISH_ENABLED set to true.

    Running

    Invoke just like any other npm script:

    # Start the container for local development 
    $ npm run xpr:start
     
    # Commit your changes 
    $ git commit -m "further awesomeness added"
     
    # Build, tag and push the container to the specified Docker repo 
    $ npm run xpr:push
     
    # Deploy the container to production 
    $ npm run xpr:deploy production

    Verbose output

    Exp-containership edheres to the npm loglevel, so to get more output during troubleshooting etc:

    $ npm --loglevel verbose run deploy production

    Hooks

    To define deploy hooks, we utilize the pre/post feature built into the npm script tasks. You can define your own scripts and/or use the ones that come with exp-deploy described below.

    Pre

    • exp-ensure-unmodified - ensures that everything is commited to git
    • exp-ensure-master - ensure that we deploy only from the master branch.
    • exp-ensure-tests - ensure that all tests are running.
    • exp-ensure-container-tests - ensures that everything is commited to git

    Post

    • exp-set-tag - sets a "deployed" tag in git to keep track of what is running in production.

    Log tailing

    You can conveniently tail log files in different environments using the log script included with exp-containership. It will use ssh to connect to the servers, so make sure to setup passwordless login or you'll risk loosing your mind from repeated username/password typing.

    Just make sure to add the following script entry to your package.json:

    "scripts": {
      ...
      "xpr:logs": "exp-logs",
      ...
    }
    

    To tail production logs on all servers (default mode):

    $ npm run xpr:logs
    

    To view all logs on all servers in some other environment:

    $ npm run xpr:logs epistage
    

    To view all logs on a specific server:

    $ npm run xpr:logs production xpr-p-app101
    

    Restarting a node

    The restart command requires both environment and host. (To see available hosts issue a "xpr:status" command).

    $npm run xpr:restart production xpr-p-app102
    

    OSX Docker

    If you are using the OSX Docker beta, set the following environment variable and exp-containership should abide.

    EXP_OSX_DOCKER=true
    

    Issues

    Certificate issue

    Example error message:

    Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host "192.168.99.100:2376": x509: certificate is valid for 192.168.99.101, not 192.168.99.100
    You can attempt to regenerate them using 'docker-machine regenerate-certs [name]'.
    Be advised that this will trigger a Docker daemon restart which will stop running containers.
    

    run:

    docker-machine regenerate-certs -f exp-docker

    Keywords

    none

    Install

    npm i exp-containership

    DownloadsWeekly Downloads

    7

    Version

    0.3.14

    License

    MIT

    Last publish

    Collaborators

    • alau
    • cldmnky
    • joelabrahamsson
    • nordbergm
    • norla
    • oscartholander
    • theneubeck