develop# Getting Started Building and Deploying with Distelli - NodeJS Example

This tutorial will get you setup, building, testing, and deploying an application with Distelli in minutes.

The tutorial assumes you have already:

• Created a free Distelli account
• Have a login to, at least, one of the two public repositories.

• https://github.com/
• https://bitbucket.org/

The scenario also expects that you have a Destination server available to do deployments of the example application.

Step 1. Prepare Server for Deployment

To enable auto deployment of an application you must have a destination server to deploy to.

If you don't have a server you can use a virtual server. For a simple guide to setting up a virtual server using Virtualbox and Vagrant see Building Virtual Servers.

You must install the Distelli agent on the server to facilitate deployments. Instructions on installing the Distelli agent can be found here Distelli agent reference guide.

Install the agent and return to this document.

Step 2. Fork and Clone the Repository

Fork Github Repository

1. Ensure you are logged into your Github account. https://github.com/
2. Go to this pubilc Distelli repository: https://github.com/distelli/nodejsbuilddeploy.
3. Click the Fork button (top right).

You have forked the repository to your Github account. Good job!

You can view the forked repository in your Github account at:

https://github.com/YOUR_GITHUB_USERNAME/nodejsbuilddeploy

Clone Github Repository

You will need to clone a copy of the repository to your local machine. This assume you already have git installed on your local computer. If not you can install git from here: http://git-scm.com/

Use the following syntax to clone the repository:

git clone https://github.com/YOUR_GITHUB_USERNAME/nodejsbuilddeploy.git

Now change to the newly created directory.

cd nodejsbuilddeploy

Note: If your Github account is using Two-factor authentication you will not be able to use the above command to clone and work with the repository. You must:

• Use an SSH key with github https://help.github.com/articles/generating-ssh-keys/
• Use a different git clone syntax. See below:

git clone git@github.com:YOUR_GITHUB_USERNAME/nodejsbuilddeploy.git

Step 3. Edit the Distelli Manifest

The Distelli Manifest file provides the Distelli Platform with the needed information to successfully build and deploy your application. This file must exist before building your application with Distelli.

The sample application you cloned will already have an existing distelli-manifest.yml file in the application root directory. You will need to make a small change to this file before you can build and deploy the application with Distelli.

Edit the distelli-manifest.yml file.

On the first line you will see a <username> placeholder, and then the name of the sample application.

Replace the <username> placeholder with your Distelli username. To find your Distelli username see Finding Your Distelli Username.

For example if your username is 'YourUserName' your distelli-manifest.yml should look like this:

YourUserName/nodejsbuilddeploy:
  Build:
    - echo "---Building---"
    - npm install
    - echo "--Testing--"
    - npm test

  PkgInclude:
    - '*'

  PreInstall:
    - echo "---Begining PreInstall---"
    - echo "--Installing deploy dependencies--"
    - echo "-Updating apt-get-"
    - sudo apt-get -y update
    - echo "-Installing nodejs-"
    - sudo apt-get -y install nodejs

  PostInstall:
    - echo "Begin PostInstall"

  Env:
    - PORT: "3000"

  Exec:
    - nodejs app.js

Save your change.

Step 4. Create the Application

In this step you will use the Distelli new application workflow to create an application that is integrated with the repository you forked above.

To complete this section you will navigate to another set of instructions. There you will walk through those instructions, afterwards returning here.

Certain fields will need tutorial specific information. The table below has that information.

Name	Value
Name your App Application Name	nodejsbuilddeploy
Choose a Repo Repository Name	nodejsbuilddeploy
Choose a Branch Branch Name	master

After completing the Tutorial Creating an Application from a Repository return to this tutorial document.

Navigate to Tutorial Creating an Application from a Repository, follow the steps in the document, and then return here.

Return here!

Step 5. Enable Auto Build

1. In the Distelli WebUI click Applications at the top.

2. In the application list click nodejsbuilddeploy name to navigate to the application page.

3. Click the Settings link.

   You are now in the application settings page.

4. Check the Automatically build this branch when a new commit is pushed box.

5. Click Save Repo Settings

You have enabled auto build.

If you are interested in building on your own build server(s) see Using your own Build Server.

Step 6. Enable Auto Deploy

1. In the Distelli WebUI click the Applications link at the top.

2. In the application list click nodejsbuilddeploy name to navigate to the application page.

3. Click the Settings link.

   You are now in the application settings page.

4. Scroll down and find the Repository Settings section.

5. Check the Automatically deploy this branch when a build succeeds box.

6. Click on the nodejsbuilddeploy-beta environment to select it.

7. Click Save Repo Settings

You have enabled auto deploy.

Step 7. Add Server to Environment

In the last step you enabled auto deploy for the application environment, but this environment currently has no servers in it to deploy to.

In this step you will add the server, from step 1, to the -beta environment.

1. In the Distelli WebUI click the Applications link at the top.

2. In the application list click nodejsbuilddeploy name to navigate to the application page.

3. Click the Environments link.

4. Click the nodejsbuilddeploy-beta environment.

   You are now at the environment page.

5. Click the Servers link in the environment section.

6. Click Add Servers.

   You should see the server from step 1 in the server list.

7. Check the Add Server box for the server from step 1.

8. Click the Add Selected Servers link near the top left

You have added a server to the environment.

Step 8. Trigger a Build

In a previous step you edited and saved the distelli-manifest.yml file in the nodejsbuilddeploy application directory. This constitutes a code change. You will now commit and push that code change up to your repository.

When the repository changes it will notify Distelli that a change occurred. This will trigger a build by Distelli.

Distelli will grab a copy of the repository; build it, test it, and if it is successful will create a release.

When a release is created this will trigger an auto deploy of the application to the -beta environment with the server from step 1.

Push with Github

Enter the following commands in the nodejsbuilddeploy directory:

git add .
git commit -m "Set username in manifest"
git push -u origin master

This will push your code change up to the repository.

Step 9. Watch the Build and Deploy Process

1. Click the Builds link at the top of the Distelli WebUI.

   In the builds list page you will see your build queued or in progress

2. Click on the build to navigate to the build page.

   From the build page you can watch the build log. If the build fails see the Troubleshooting section below.

Step 10. Validation

To verify the application deployed correctly point your web browser to your destination server IP on port 3000.

http://YOUR_SERVER_IP:3000

Understanding the Distelli Manifest

The distelli-manifest.yml provides the instructions for building, testing, and deploying the application.

For more information on the Distelli manifest see Distelli Manifest.

Troubleshooting

Incorrect Manifest

If you see the following build failure:

Task Status: Exit=1 Signal=0

Cloning into '/distelli/tasks/d461-762'...
HEAD is now at 7db094e Update distelli-manifest.yml
Expected manifest(s) to contain app 'YourUserName/gobuilddeploy'. Instead the manifest(s) specified:
  '<username>/gobuilddeploy'

Ensure that you:

• Correctly edited the distelli-manifest.yml Step 3.
• Committed and pushed the repository Step 8.

Deploy Failure

For more information on troubleshooting deploys see Troubleshooting Deploys.

Next

• Tutorials Index
• Manifest Library of Examples
• Read the Knowledge Base articles
• Check out the Reference Guides