NodeJS应用部署指南
########################

入门指南
============

准备工作
-------------

首先，我们从github上clone一个nodejs的示例程序。

.. code-block:: console

    $ git clone https://github.com/sinacloud/nodejs-getting-started.git
    $ cd nodejs-getting-started
    $ ls
    README.md    index.js     package.json

示例代码中包含了三个文件，其中 *index.js* 是代码文件， *package.json* 是 `npm <https://www.npmjs.com/>`_ 的包管理描述文件。

*index.js* 的代码如下，这是一个简单的 `Express <http://expressjs.com/>`_ 应用，注意代码的最后一行，所有的NodeJS应用都需要监听环境变量的 *PORT* 指定的端口（默认为5050），并处理这个端口收到的所有HTTP请求。

.. code-block:: js

    var express = require('express')
    var app = express()

    app.get('/', function (req, res) {
      res.send('Hello World')
    })

    app.listen(process.env.PORT || 5050)

下面是 *package.json* 的代码，其中的 *dependencies* 指定了本示例程序的依赖包， *scripts/start* 里指定了如何运行本示例代码。（新浪云在部署应用的时候会根据这个文件来安装应用相关的依赖以及来启动应用程序）。

.. code-block:: json

    {
      "name": "nodejs-getting-started",
      "description": "getting started with nodejs on sinacloud platform",
      "version": "0.0.1",
      "private": true,
      "author": {
        "name": "sae",
        "email": "saemail@sina.cn"
      },
      "dependencies": {
        "express": "^4.13.3"
      },
      "engines": {
        "node": "0.10.36"
      },
      "scripts": {
        "start": "node index.js"
      }
    }

我们执行 *npm install* && *npm start* ，在本地运行这个示例程序，现在我们可以通过 http://localhost:5050 来访问我们的应用了。

.. code-block:: console

    $ npm install && npm start
    express@4.13.3 node_modules/express
    ├── escape-html@1.0.2
    ...
    └── send@0.13.0 (destroy@1.0.3, statuses@1.2.1, ms@0.7.1, mime@1.3.4, http-errors@1.3.1)

    > nodejs-getting-started@0.0.1 start /private/tmp/nodejs_helloworld
    > node index.js

.. include:: ./deploy-to-sinacloud.snippet.rst

构建和运行说明
===============

如何识别应用是NodeJS应用？
-------------------------------

新浪云容器通过通过判断应用根目录下是否存在 **package.json** 文件来判断一个应用是否是NodeJS应用。

指定NodeJS版本
---------------

部署应用的时候，最好指定你需要用到的NodeJS版本（使用和你本地测试用的版本一致）。如果不指定，容器云构建的时候默认会使用目前版本最高的stable版本。

.. code-block:: console

    $ node --version
    v4.1.1

你可以在 **package.json** 中指定你要使用的NodeJS版本（删掉上面最前面的‘v’，只保留版本号）。

.. code-block:: json

    {
      "name": "myapp",
      "description": "a really cool app",
      "version": "1.0.0",
      "engines": {
        "node": "4.1.1"
      }
    }

指定Npm版本
--------------

大部分时候，你不需要单独指定npm版本，使用NodeJS自带的npm就可以了。

Npm 2.1.x 以前的版本有很多已知的问题，如果你使用的NodeJS版本的npm比较老，你可以通过以下方法指定你要使用的npm版本。

.. code-block:: json

    {
      "name": "myapp",
      "description": "a really cool app",
      "version": "0.0.1",
      "engines": {
        "npm": "2.1.x"
      }
    }

自定义构建过程
----------------

如果你有一些自定义的脚本需要在构建的时候运行，你可以使用npm的postinstall脚本，该脚本会在所有构建动作完成后最后执行，例：

.. code-block:: json

    {
      "scripts": {
        "start": "node index.js",
        "test": "mocha",
        "postinstall": "bower install && grunt build"
      }
    }

Runtime说明
--------------

服务端最终调用 `npm start` 来启动应用。

常见问题
===========

确保应用的依赖模块在package.json中有定义
---------------------------------------------

当使用 ``npm install`` 安装模块的时候，模块会被安装到依赖的 `node_modules` 目录下，但是这个依赖模块却并没有被添加到 `package.json` 文件中。这个时候应用在本地可以运行，但是部署到服务器上时会因为缺少依赖的关系而运行失败。

所以，安装模块的时候最好使用 ``npm install --save`` 来安装模块， ``--save`` 会在安装模块的同时将依赖添加到 `package.json` 文件里。

同理，不要依赖全局的模块。