ember-cli-deploy-ssh-index

An ember-cli-deploy plugin to upload revisions to a remote server via SSH

This plugin uploads a file, presumably index.html, to a specified folder on a remote server via SSH.

This plugin is heavily based on ember-cli-deploy-s3-index and ember-cli-deploy-ssh

What is an ember-cli-deploy plugin?

A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.

For more information on what plugins are and how they work, please refer to the Plugin Documentation.

Quick Start

To get up and running quickly, do the following:

• Ensure ember-cli-deploy-build is installed and configured.

• Ensure ember-cli-deploy-revision-data is installed and configured.

• Ensure ember-cli-deploy-display-revisions is installed and configured.

• Install this plugin

$ ember install ember-cli-deploy-ssh-index

• Place the following configuration into config/deploy.js

ENV['ssh-index'] = {
  username: '<your-remote-username>',
  host: '<your-remote-host>',
  remoteDir: '<your-remote-directory>',
  privateKeyFile: '<absolute-path-to-private-key>'
}

• Run the pipeline

$ ember deploy

Installation

Run the following command in your terminal:

ember install ember-cli-deploy-ssh-index

ember-cli-deploy Hooks Implemented

For detailed information on what plugin hooks are and how they work, please refer to the Plugin Documentation.

• upload
• activate
• fetchRevisions

Configuration Options

For detailed information on how configuration of plugins works, please refer to the Plugin Documentation.

Required configuration options

filePattern (required)

A file matching this pattern will be uploaded to your remote host. The active revision on the host will match filePattern. The versioned keys will have revisionKey appended (Ex: index.html:39a2f02).

Default: 'index.html'

host (required)

The remote host to which the revision will be deployed.

Default: undefined

port (required)

The port of the remote host.

Default: 22

privateKeyFile (required)

The path to the private key to use when connecting to the remote host. Ex: '~/.ssh/id_rsa'

Default: undefined

remoteDir (required)

The directory on the remote host to which the revision will be deployed.

Default: undefined

username (required)

The username to use when connecting to the remote host.

Default: undefined

Optional configuration options

allowOverwrite

A flag to specify whether the revision should be overwritten if it already exists on the remote host.

Default: false

distDir

The root directory where the file matching filePattern will be searched for. By default, this option will use the distDir property of the deployment context.

Default: context.distDir

passphrase

The passphrase used to protect your privateKeyFile.

For security, this should be passed in via an environment variable.

{
  'ssh-index': {
    // Other configuration...
    passphrase: process.env.PRIVATE_KEY_PASSPHRASE
  }
}

Default: undefined

revisionKey

The unique revision number for the version of the file being uploaded to the remote host. By default this option will use either the revisionKey passed in from the command line or the revisionKey property from the deployment context.

Default: context.commandLineArgs.revisionKey || context.revisionKey

How do I activate a revision?

A user can activate a revision by either:

• Passing a command line argument to the deploy command:

$ ember deploy staging --activate

• Running the deploy:activate command:

$ ember deploy:activate --revision <revision-key>

• Setting the activateOnDeploy flag in deploy.js

ENV.pipeline {
  activateOnDeploy: true
}

What does activation do?

When ember-cli-deploy-ssh-index uploads a file to a remote host, it uploads it under the key defined by a combination of the two config properties filePattern and revisionKey.

So, if the filePattern was configured to be index.html and there had been a few revisons deployed, then remoteDir on your remote host might look something like this:

$ ls -l <remoteDir>
-rw-rw-r-- 1 ec2-user ec2-user     1 Dec 10 22:45 a644ba4.active-revision
-rw-rw-r-- 1 ec2-user ec2-user 22616 Dec 10 22:45 index.html
-rw-rw-r-- 1 ec2-user ec2-user 22616 Dec 10 22:45 index.html:a644ba4
-rw-rw-r-- 1 ec2-user ec2-user 22616 Dec  8 05:38 index.html:61cfff6
-rw-rw-r-- 1 ec2-user ec2-user 22616 Dec  1 10:22 index.html:9dd26db

Activating a revision would copy the content of the passed revision to index.html which would be served up by a web server (such as Nginx) on your remote host. Activating one of the revisions above would look like this:

$ ember deploy:activate --revision a644ba4

Additionally, activation creates an empty file where the filename is the revision key, with an extension of .active-revision. This is what is used to determine the currently active revision on the remote host. On activation, all previous .active-revision files are removed and a new one is created, based on the revision being activated.

When does activation occur?

Activation occurs during the activate hook of the pipeline. By default, activation is turned off and must be explicitly enabled by one of the 3 methods above.

Prerequisites

The following properties are expected to be present on the deployment context object:

• distDir (provided by ember-cli-deploy-build)
• project.name() (provided by ember-cli-deploy)
• revisionKey (provided by ember-cli-deploy-revision-key)
• commandLineArgs.revisionKey (provided by ember-cli-deploy)
• deployEnvironment (provided by ember-cli-deploy)