Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
634 lines (582 sloc) 20.4 KB
<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta charset="utf-8">
<title>The Nodejitsu Handbook</title>
<meta name="description" content="The Nodejitsu Handbook - A gentle introduction to the art of Nodejitsu" />
<meta name="author" content="Nodejitsu Inc" />
<meta name="viewport" content="width=device-width" />
<link rel="stylesheet" href="/css/base.dev.css">
<link rel="stylesheet" href="/css/github.min.css">
<link rel="icon" type="image/png" href="img/favicon.png">
<script src="/js/highlight.min.js"></script>
<script src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.3.min.js"></script>
<script src="/js/slugify.js"></script>
<script>
hljs.tabReplace = ' ';
hljs.initHighlightingOnLoad();
</script>
</head>
<body class="container">
<nav role="navigation" class="navigation">
<div class="row">
<ul>
<li><a href="/" class="sprite logo hide-text">Nodejitsu Inc.</a></li>
</ul>
</div>
</nav>
<div class="row">
<aside class="tableofcontents threecol" role="complementary">
<h2>Table of contents</h2>
<div id="toc">
<ul class="vertical-tabs">
<li class="tree">
<div class="page-details">
<a href="/a-quickstart" class="title">Quickstart</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/a-quickstart/faq" class="title">FAQ</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/a-quickstart/hello-world" class="title">Hello World: A Tutorial</a>
</div>
</li>
</ul><ul class="vertical-tabs">
<li class="tree">
<div class="page-details">
<a href="/features" class="title">Platform Features</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/features/webhooks" class="title">Continuous Deployment</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/features/webops" class="title">Using Webops</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/features/jitsu" class="title">Using the jitsu CLI</a>
</div>
</li>
</ul><ul class="vertical-tabs">
<li class="tree">
<div class="page-details">
<a href="/support" class="title">Need Support?</a>
</div>
</li>
</ul><ul class="vertical-tabs">
<li class="tree">
<div class="page-details">
<a href="/api" class="title">JSON API</a>
</div>
</li>
</ul><ul class="vertical-tabs">
<li class="tree">
<div class="page-details">
<a href="/appendix" class="title">Appendix</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/appendix/resources" class="title">More Resources</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/appendix/open-source" class="title">Open Source Projects</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/appendix/haibu" class="title">Run it yourself With Haibu</a>
</div>
</li><li class="tree">
<div class="page-details">
<a href="/appendix/package-json" class="title">Understanding package.json</a>
</div>
</li>
</ul></div>
</aside>
<div class="full-height threecol"></div>
<div class="content eightcol" role="main">
<article id="content" class="tab-content intro"><div>
<div class="page-details">
<a class="view-github" href="https://github.com/nodejitsu/handbook/blob/master/content/articles/features/webhooks.md">View on Github</a>
<h1 class="title">Continuous Deployment</h1>
</div>
<div class="content"><p><a name="webhookapi-index"></a>
Access the <code>Admin</code> section on your open source node.js Github repository. Click <code>Service Hooks</code> and then <code>Nodejitsu</code>. You will be presented with a form with four fields:
</p>
<ul>
<li>Username, which defaults to your Github username</li>
<li>Password, your password or a valid <a href="https://handbook.nodejitsu.com/api#create-an-api-token">Nodejitsu API authentication token</a></li>
<li>Branch, where you can define the branch you wish to deploy and defaults to master</li>
<li>Endpoint, which defaults to <a href="https://webhooks.nodejitsu.com">https://webhooks.nodejitsu.com</a></li>
</ul>
<p><img src="https://lh4.googleusercontent.com/-kiN3YkEG_ys/UJqQ-4aGJbI/AAAAAAAADFc/esjmrqD_2IY/s945/Screenshot%252B2012-11-07%252Bat%252B16.42.57.png" alt="The Github Interface for Nodejitsu">
</p>
<p>Select <code>Active</code> and hit <code>Update Settings</code>. From now on every-time you commit to Github (in the designated deployment branch) we will deploy that application for you. That simple.
</p>
<p><a name="webhookapi-monitoring"></a>
</p>
<h2>Monitoring deployments</h2>
<p>There&#39;s several ways to access the deployment status in the Nodejitsu Webhook API, and you can find the complete documentation at <a href="http://webhooks.nodejitsu.com">webhooks.nodejitsu.com</a>.
</p>
<p>The most fun way to monitor your deployment is with the realtime status changes feed.
</p>
<pre><code class="lang-bash"><span class="comment"># if your username is foo and password is bar this would be </span>
<span class="comment"># https://foo:bar@webhooks.nodejitsu.com/1/status/foo/changes</span>
curl -u username https://webhooks.nodejitsu.com/1/status/username/changes?include_docs=auto</code></pre>
<p>This will create an HTTP keep alive connection that pushes the status to you in realtime every time someone invokes our API:
</p>
<pre><code class="lang-js">{
<span class="string">"id"</span>: <span class="string">"https://webhooks.nodejitsu.com/1/status/dscape/changes/2b3de47c2ce04a9dda4d31aac5000bab"</span>,
<span class="string">"app_name"</span>: <span class="string">"hello-world-api-flatiron"</span>,
<span class="string">"uuid"</span>: <span class="string">"aa6e9b1332436698771"</span>,
<span class="string">"status"</span>: <span class="string">"ok"</span>,
<span class="string">"provider"</span>: <span class="string">"travis"</span>,
<span class="string">"commit"</span>: <span class="string">"dscape/hello-world-flatiron-api/96410ed970f6224a4cd3c450150c5d65bbc77fcd"</span>
}</code></pre>
<p>Each request to our API is logged with a unique <code>uuid</code>, so you can use it to refer possible issues to our support staff.
</p>
<p>We are now ready to deploy, go back to Github and click <code>Test Hook</code>. You should be up and running shortly.
</p>
<p><a name="webhookapi-travis"></a>
</p>
<h2>Travis</h2>
<p>What about continuous integration? We added <a href="http://travis-ci.org/">Travis-CI</a> so you can feel safe about your deployments. Simply add something like this in your <code>.travis.yml</code> file.
</p>
<pre><code>notifications:
webhooks:
urls:
- http://webhooks.nodejitsu.com/1/deploy
on_success: always
on_failure: never</code></pre>
<p>Internally our API will try to see if you have Travis configured like this, and if you do it will put the deployment request from Github on a hold until Travis informs us all tests have passed.
</p>
<p>If tests failed we won&#39;t deploy. Simple.
</p>
<p><a name="webhookapi-privaterepos"></a>
</p>
<h2>Deploying Private Repos &amp; Commit Status API</h2>
<p>If you authorize access so we can use your github account we can do more fun stuff like allowing you to deploy your private repositories, or even update your <a href="https://github.com/blog/1227-commit-status-api">commit status</a> and check if a deployment worked directly in github. We don&#39;t save any passwords - we just use the password to retrieve a token to save.
</p>
<p><img src="https://lh5.googleusercontent.com/-UK1ktEYEDqo/UKb8QKsaaNI/AAAAAAAADF0/5Pvdkh1_SDM/s829/Screenshot%252B2012-11-17%252Bat%252B02.29.29.png" alt="Commit Status API">
</p>
<p>To authorize simply do:
</p>
<pre><code class="lang-bash">curl -X POST \
-H <span class="string">"Content-type: application/json"</span> \
--data <span class="string">"{ \"credentials\": \"githubUser:githubPassword\" }"</span> \
https://nodejitsuUser:nodejitsuPass@webhooks.nodejitsu.com/1/auth/github</code></pre>
<p><a name="webhookapi-apikeys"></a>
</p>
<h2>But wait, I have API keys I can&#39;t commit to Github as open source?!</h2>
<p>Don&#39;t worry, you can use <code>jitsu set env</code> to set environment variables that you can access with <code>process.env</code>. Check our <a href="https://handbook.nodejitsu.com/features#feature/envvars">handbook</a> for more information. Environment variables set this way persist across deployments and are also available in our <a href="https://webops.nodejitsu.com">webops</a> application.
</p>
<p><a name="webhookapi-api"></a>
</p>
<h2>API Documentation</h2>
<p><a name="deploy"></a>
</p>
<h3>Deploy</h3>
<pre><code>POST /
POST /1/deploy</code></pre>
<p>Deploy a new application with a given payload.
</p>
<p>Check <a href="#payloads">Sample Payloads</a> for examples. This method is normally called by a <a href="http://help.github.com/post-receive-hooks">github</a> or <a href="http://about.travis-ci.org/docs/user/build-configuration">travis</a> web-hook.
</p>
<p>You must configure the github webhook to use the travis webhook. Works under the assumption that if your repository has a <code>.travis.yml</code> file and that contains at least one webhook notification we shouldn&#39;t deploy from the github request, but instead wait until travis triggers the notify event and calls our API. This effectively means that if travis tests don&#39;t pass your application does not get deployed.
</p>
<pre><code>curl -X POST -u username -d @file https://webhooks.nodejitsu.com/1/deploy</code></pre>
<p>Authentication can use a pair of <code>user:pass</code> or <code>user:apiToken</code>.
</p>
<p><a name="deploy-accept"></a>
</p>
<h4>Accept</h4>
<table>
<tr>
<th>Content-type</th>
<th>Description</th>
</tr>
<tr>
<td>application/json</td>
<td>A valid JSON payload</td>
</tr>
</table>
<p><a name="deploy-headers"></a>
</p>
<h4>Response Headers</h4>
<table>
<tr>
<th>Header</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>x-api-uuid</td>
<td>String - UUID</td>
<td>A unique id for your request. We keep tracks of these to help you thru support</td>
</tr>
<tr>
<td>x-api-version</td>
<td>String - Semantic Version</td>
<td>The current version of our API. Follows semver rules. Major version is in the url as first parameter.</td>
</tr>
</table>
<p><a name="deploy-errors"></a>
</p>
<h4>Errors</h4>
<table>
<tr>
<th>Error</th>
<th>Status Code</th>
<th>Reason</th>
</tr>
<tr>
<td>deploy:db:failed_to_store_payload</td>
<td>503</td>
<td>Our database isn&#39;t responding or timed out</td>
</tr>
<tr>
<td>deploy:provider:not_supported</td>
<td>400</td>
<td>You tried to deploy an invalid payload</td>
</tr>
<tr>
<td>deploy:github:no_pkg_json</td>
<td>502</td>
<td>We couldn&#39;t get package.json from github. This may happen because you are trying to deploy a private repo</td>
</tr>
<tr>
<td>deploy:auth:bad_creds</td>
<td>401</td>
<td>You didn&#39;t provide valid Basic Auth in your HTTP request</td>
</tr>
<tr>
<td>deploy:github:download_tarball</td>
<td>502</td>
<td>Failed to get the tarball from github</td>
</tr>
<tr>
<td>deploy:nodejitsu:upload_tarball</td>
<td>502</td>
<td>Failed to upload the tarball to nodejitsu</td>
</tr>
<tr>
<td>deploy:tar:*</td>
<td>500</td>
<td>There was a system failure when extracting the tar</td>
</tr>
<tr>
<td>deploy:nodejitsu:start_app</td>
<td>500</td>
<td>Failed to start nodejitsu application</td>
</tr>
<tr>
<td>deploy:no_payload</td>
<td>400</td>
<td>You didn&#39;t provide a payload</td>
</tr>
</table>
<p><a name="status"></a>
</p>
<h3>Status</h3>
<pre><code>GET /1/status/:user/webhooks
GET /1/status/:user/webhooks/:application</code></pre>
<p>Gets the install status for a specific user. Useful to determine if the deploy worked, or why it failed. <code>:user</code> is your nodejitsu username and <code>:application</code> is your application name.
</p>
<pre><code>curl -u dscape https:/webhooks.nodejitsu.com/1/status/dscape/webhooks/hello-world-api-flatiron?limit=10\&amp;skip=20</code></pre>
<p><a name="status-qs"></a>
</p>
<h4>Query String Parameters</h4>
<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>limit</td>
<td>Integer</td>
<td>Number of log entries to display per page</td>
</tr>
<tr>
<td>skip</td>
<td>Integer</td>
<td>Number of log entries to skip. e.g. if you saw 10 already, you might do a skip=10</td>
</tr>
</table>
<p><a name="status-headers"></a>
</p>
<h4>Response Headers</h4>
<table>
<tr>
<th>Header</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>x-api-uuid</td>
<td>String - UUID</td>
<td>A unique id for your request. We keep tracks of these to help you thru support</td>
</tr>
<tr>
<td>x-api-version</td>
<td>String - Semantic Version</td>
<td>The current version of our API. Follows semver rules. Major version is in the url as first parameter.</td>
</tr>
</table>
<p><a name="status-errors"></a>
</p>
<h4>Errors</h4>
<table>
<tr>
<th>Error</th>
<th>Status Code</th>
<th>Reason</th>
</tr>
<tr>
<td>mw:auth:not_you</td>
<td>401</td>
<td>You are trying to get status that don&#39;t belong to you</td>
</tr>
<tr>
<td>mw:auth:auth_server_down</td>
<td>500</td>
<td>We couldn&#39;t verify your credentials</td>
</tr>
<tr>
<td>mw:auth:unauthorized</td>
<td>401</td>
<td>Your username/password combination doesn&#39;t match our records</td>
</tr>
<tr>
<td>mw:auth:no_username</td>
<td>401</td>
<td>Your user document is in a bad state, contact support</td>
</tr>
<tr>
<td>status:db:not_found</td>
<td>404</td>
<td>Didn&#39;t find that log entry</td>
</tr>
<tr>
<td>status:db:get_by_id</td>
<td>500</td>
<td>The database couldn&#39;t complete your query</td>
</tr>
<tr>
<td>status:db:query_fail</td>
<td>500</td>
<td>The database couldn&#39;t complete your query</td>
</tr>
</table>
<p><a name="changes"></a>
</p>
<h3>Changes</h3>
<pre><code>GET /1/status/:user/changes/
GET /1/status/:user/changes/:id</code></pre>
<p>Streams log files as you deploy application with a changes stream. When you provide an id it will just return that entry and close the http connection.
</p>
<pre><code>curl -u dscape https://webhooks.nodejitsu.com/1/status/dscape/changes?include_docs=true</code></pre>
<p><a name="changes-qs"></a>
</p>
<h4>Query String Parameters</h4>
<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>include_docs</td>
<td>Boolean</td>
<td>Will add an extra property <code>doc</code> (containing the full log document) to each log entry that is displayed. Use &quot;auto&quot; for automatically expanding errors and summarizing ok statuses</td>
</tr>
</table>
<p><a name="changes-headers"></a>
</p>
<h4>Response Headers</h4>
<table>
<tr>
<th>Header</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>x-api-uuid</td>
<td>String - UUID</td>
<td>A unique id for your request. We keep tracks of these to help you thru support</td>
</tr>
<tr>
<td>x-api-version</td>
<td>String - Semantic Version</td>
<td>The current version of our API. Follows semver rules. Major version is in the url as first parameter.</td>
</tr>
</table>
<p><a name="changes-errors"></a>
</p>
<h4>Errors</h4>
<table>
<tr>
<th>Error</th>
<th>Status Code</th>
<th>Reason</th>
</tr>
<tr>
<td>mw:auth:not_you</td>
<td>401</td>
<td>You are trying to get status that don&#39;t belong to you</td>
</tr>
<tr>
<td>mw:auth:auth_server_down</td>
<td>500</td>
<td>We couldn&#39;t verify your credentials</td>
</tr>
<tr>
<td>mw:auth:unauthorized</td>
<td>401</td>
<td>Your username/password combination doesn&#39;t match our records</td>
</tr>
<tr>
<td>mw:auth:no_username</td>
<td>401</td>
<td>Your user document is in a bad state, contact support</td>
</tr>
<tr>
<td>status:db:query_fail</td>
<td>500</td>
<td>The database couldn&#39;t complete your query</td>
</tr>
<tr>
<td>status:changes:timeout</td>
<td>408</td>
<td>The socket connection timeout. Please re-connect</td>
</tr>
<tr>
<td>status:changes:fatal</td>
<td>500</td>
<td>There was an error in the underlying connection</td>
</tr>
</table>
<p><a name="auth"></a>
</p>
<h3>auth</h3>
<pre><code>POST /1/auth/github</code></pre>
<p>Tries to get authorization from github, so elevated privileges can be used on that service. This will give us access to get working code from your repositories and change the status of a specific pull request
</p>
<pre><code>curl -X POST -u nodejitsuUser https://webhooks.nodejitsu.com/1/auth/github \
--data &#39;{&quot;credentials&quot;:&quot;githubUser:githubPass&quot;}&#39; \
--header &quot;Content-type: application/json&quot;</code></pre>
<p><a name="auth-qs"></a>
</p>
<h4>Query String Parameters</h4>
<p>The <code>app</code> parameter exists so you can restrict usage of a token to a individual application. This is useful can then commit status can only be applied to that specific application, and other third party tokens will not be returned.
</p>
<p>However be careful, when specifying an application we will not be able to use these credentials to access the repository (because when we do that for the first time we still don&#39;t know the app name, we learn that from the package.json file).
</p>
<p>Bottom line if you want to do deployments for private repositories do not specify <code>app</code> or you will fail.
</p>
<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>app</td>
<td>String</td>
<td>Will restrict the usage of this token to a application. If not provided a wildcard will be used.</td>
</tr>
</table>
<p><a name="auth-headers"></a>
</p>
<h4>Response Headers</h4>
<table>
<tr>
<th>Header</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>x-api-uuid</td>
<td>String - UUID</td>
<td>A unique id for your request. We keep tracks of these to help you thru support</td>
</tr>
<tr>
<td>x-api-version</td>
<td>String - Semantic Version</td>
<td>The current version of our API. Follows semver rules. Major version is in the url as first parameter.</td>
</tr>
</table>
<p><a name="auth-errors"></a>
</p>
<h4>Errors</h4>
<table>
<tr>
<th>Error</th>
<th>Status Code</th>
<th>Reason</th>
</tr>
<tr>
<td>mw:auth:not_you</td>
<td>401</td>
<td>You are trying to get status that don&#39;t belong to you</td>
</tr>
<tr>
<td>mw:auth:auth_server_down</td>
<td>500</td>
<td>We couldn&#39;t verify your credentials</td>
</tr>
<tr>
<td>mw:auth:unauthorized</td>
<td>401</td>
<td>Your username/password combination doesn&#39;t match our records</td>
</tr>
<tr>
<td>mw:auth:no_username</td>
<td>401</td>
<td>Your user document is in a bad state, contact support</td>
</tr>
<tr>
<td>auth:github:get_user_failed</td>
<td>500</td>
<td>When retrieving the user from the nodejitsu api we got a non 200 response. The api might be down, or perhaps authorization credentials where changed</td>
</tr>
<tr>
<td>auth:github:update_user_failed</td>
<td>500</td>
<td>We tried to update the user but it failed. Just like above, reasons are varied so contact support if you see this</td>
</tr>
<tr>
<td>auth:github:no_credentials</td>
<td>400</td>
<td>Credentials were not provided. Check query string parameters for details</td>
</tr>
<tr>
<td>auth:github:bad_credentials</td>
<td>400</td>
<td>Credentials were provided but not in the username:password format. Check query string parameters for details</td>
</tr>
<tr>
<td>auth:github:github_pairing_failed</td>
<td>401</td>
<td>We tried to authenticate with github but it failed</td>
</tr>
</table>
</div>
</div></article>
</div>
<!-- content -->
</div>
<!-- row -->
<footer role="contentinfo" class="copyright">
<p>&copy; 2010-2012 Nodejitsu Inc.</p>
<a href="http://legal.nodejitsu.com/privacy" class="last">Privacy policy</a>
<a href="http://legal.nodejitsu.com/terms-of-service">Terms of Service</a>
</footer>
<script src="../public/js/ui.js"></script>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.