- Create a new project
- Starting point
- Migrate a Node.js application to API Runtime Services
- Deploy the application
- View log files
- Declare dependencies
- Third-party tools
- Define environment variables
- Scale the application
- Custom domains
- Create child processes
- Application limitations
This guide covers managing a standard Node.js application in the API Runtime Services environment. For managing projects that use the MVC framework, see Arrow Cloud MVC Project.
API Runtime Services supports running applications built with standard Node.js. Any application that can be started and run with the node command can be run seamlessly as an API Runtime Services application. However, there are some things that you need to bear in mind when working with API Runtime Services.
Create a new project
By default, when you create a new API Runtime Services application using the
appc cloud new command, it includes the Arrow Cloud MVC Framework. To create an application without the MVC framework, pass
--framework none as a parameter to
appc cloud new:
To convert an MVC-based API Runtime Services application to a standard Node.js application, open the application's
package.json file and remove the following line:
If package.json does not include a
framework field, the application is assumed to be a standard Node.js application. Equivalently, you can set the "framework" field to "none":
For standard Node.js applications, API Runtime Services uses either the
scripts.start field in
package.json to determine the application's main entry point. For example, suppose that the main field is defined as follows in
In this case,
/app.js is first file loaded and run by API Runtime Services when the "run" command is executed to start the app locally, or when running the app in the cloud.
If your application's
package.json file does not specify a
main field, API Runtime Services checks the
scripts.start field in
package.json to determine the main module to launch. The start script is run using
npm start. For example, the
scripts.start field in the following package.json file means that
node main/index.js will be run when the application starts.
See the NPM documentation on the "scripts" package.json field.
Migrate a Node.js application to API Runtime Services
If you already have a Node.js application and would like to run it on API Runtime Services, the migration process is simple:
Login to API Runtime Services by running the following command:
When prompted, enter your account credentials.
If your application doesn't include a package.json file, create one.
Specify the application starting point using either the
mainpackage.json field, or a
scripts.startfield. See the previous section for details.
Publish the application by running the following command:
When asked if you want to create a new application, type yes. If you belong to more than one Appcelerator Platform organization, you are prompted to select the organization the application will be assigned to. Once the application is published, any dependent Node modules are loaded and the application is started. Lastly, the URL where the application is available is shown.
That's it! Your application is running in the API Runtime Services cloud.
Deploy the application
To deploy an application to API Runtime Services, run the
appc cloud publish command from the API Runtime Services project directory. Your project source code will be uploaded to the API Runtime Services where
npm install will be executed against the project, which downloads and installs any NPM module dependencies. When installation completes, the application is executed using
If the application is already deployed, you need to either increment the
version field in the
package.json file to publish a new version of the application or pass the
--force flag to the publish command to republish the application. Before republishing the application, API Runtime Services sends the
SIGTERM signal to the currently deployed application to let it shutdown gracefully. If the app does not shutdown in time, API Runtime Services will kill the application.
To deploy an application stored in a Github repository to API Runtime Services, run the
appc cloud publish --git repo=GITHUB_URL. You may optionally pass in a branch using the
branch parameter. If your repo is private, you will need to pass in either your Github account credentials with the
password parameters or personal access token generated by Github with the
access_token parameter. You may also pass in the parameters in a configuration file in JSON format.
To generate a Github personal access token:
- Log into Github.
- Click the Settings icon (gear) in the top navigation bar.
- Click Applications in the left navigation bar.
- Under Personal Access Tokens, click Generate new token.
- Make sure the repo and public_repo scopes are selected.
- Click Generate token.
The token will be available in the Applications page of your settings.
View log files
An application typically runs in the cloud, so being able to see what is happening in the application is very important. Any log output written to
stderr in the application's root process is captured and stored by API Runtime Services, and can be viewed using the Appcelerator command-line tool or in the Logs tab of the API Runtime Services Dashboard.
- Only output written by the application's root process is included in the log file; output written by child processes forked by the application's root process will not be caught.
- Errors such as syntax errors, application crashes and system level failures are logged automatically.
The Appcelerator CLI provides three commands for viewing logs for a published application, accesslog, logcat, loglist.
appc cloud accesslogcommand lists all requests processed by the Appcelerator Cloud in a specified time period. By default, a maximum of 100 log messages are returned at a time.
appc cloud loglistcommand lists your published application's log for a specific period. By default, a maximum of 100 log messages are returned at a time.
appc cloud logcatcommand tails your published application's log continuously from Appcelerator Cloud.
About logged execution times
The execution time reported by the
accesslog commands report slightly different values. The
accesslog command reports the time required by Appcelerator Cloud to handle the initial user request, pass it to your Node application for processing, and deliver the response. In contrast,
loglist only reports the execution time for your application itself, not including the time required to process the request and response. Consequently, the
accesslog execution times are a slightly longer than those of the corresponding
loglist log item. For instance, below is
And below is the corresponding
The application can import any third-party modules that are supported by standard Node.js applications. Before publishing the app to the cloud, make sure all dependencies are listed in the
dependencies field in the application's
package.json file. For example, to add support for MongoDB 1.2.0 or greater:
The API Runtime Services servers include support for third-party tools, specifically ImageMagick and PhantomJS.
Once you have added these modules as dependencies, use
Define environment variables
To set environment variables, use the
appc cloud config --set <key>=<value> command. To set more than one variable at a time, comma separate the key-value pairs.
You can access the environment variables from the application using the
process.env namespace. For example, if you set a variable called
process.env.foo to access it in the application.
To unset an environment variable, use the
appc cloud config --unset <key> command.
To check the current environment variables, use the
appc cloud config --env command.
You cannot use the following names for environment variables: "appid", "basedir", "bodyParser", "customConfig", "dirname", "framework", "fullpath", "name", "serverId", "port", "version", "NODE", "NODE_PATH", "PATH", "PWD", "PORT", "TMPDIR", and "USER".
After changing an environment variable, you will be prompted to restart the application.
The following example sets the
foo environment variables, lists all set environment variables, then unsets the
Scale the application
To customize the number of cloud servers the application can enable the auto-scaling feature to automatically scale up and down the number of cloud servers based on the number of queued requests. You specify the maximum number of queued requests that should occur before the application is scaled up. You can also specify the minimum and maximum number of servers that should be used.
The following example enables autoscaling, using a maximum of five servers, when there are at least 20 queued requests. The application is also configured to automatically scale down the number of servers when the number of queued requests drops below 20.
Set a custom domain and path
You can bind a custom domain to your application that points to either a CNAME record or A record as well as assign it a path.
The alias to set should be a valid domain name that has been already configured with either a CNAME or A record pointing to the published application's URL. Appcelerator Cloud validates the domain record before binding it to the application.
To bind a domain to an application, use the
appc cloud config --set <domain_name> command to bind a domain to the application. You can bind multiple domains to an application. Use the
--set <domain_name> parameter to bind up to five additional domains to the application.
If you need to remove a domain, use the
--remove parameter. For applications with multiple domains, you will be prompted to select which domain to remove. You may optionally pass the domain name to remove with the
To route an application based on a path with the domain name, use the
appc cloud config --path <path_name> command to set a path for the application after setting a domain. For example, if you want to bind two applications to the same domain, specify a path for each to route a client to the correct application.
The following example allows the application to be accessed from
The following example allows the LegacyApp application to be accessed from
www.foo.com/v1 and the BrandNewApp application to be accessed from
cloudapp.appcelerator.com URL that Appcelerator Cloud uses to publish your application supports a wildcard subdomain. You may append a token to the beginning of the URL that can be parsed by the application. This does not apply to custom domain names using the
acs domain command to bind the application to a CNAME or A record.
For example, if your published URL is
https://1234567890.cloudapp.appcelerator.com/, you can navigate to your application using the same domain and add a custom token as the subdomain, for example,
deadbeef is the wildcard subdomain. Then, the application can retrieve the host and subdomain:
Create child processes
A single instance of Node runs in a single thread. To take advantage of multi-core systems, you can launch a cluster of Node processes to handle the load. Applications can use the core Node Cluster module to easily create child processes that all share server ports.
To use this feature you application uses cluster.setupMaster() to set a path to a custom file to use for each child process. A cluster should listen on port 9000 or greater to avoid port conflicts. If the port your application is trying to listen on is in use, a
EADDRINUSE error will result. Your application must also have privileges to listen on the specified port, otherwise an
EACCES error will result.
Each application can use 1.8 GB of diskspace. The application can only write files to the project's root directory and to the
Each application runs in a specific container size with different resources (memory and number of CPUs). By default, when the application is published, it will run in one Dev container.
- To specify a bigger container for the application, use the
appc cloud servercommand.
- To use more than one container for your application, enable auto-scaling with the
appc cloud configcommand.
You can specify one of the following container sizes depending on your Appcelerator Platform subscription:
|Name||Point Cost||Memory||CPUs||Archive Behavior|
|Dev||1||256 MB||1||After an hour of inactivity|
|Small||2||256 MB||1||After a week of inactivity|
|Medium||4||512 MB||2||After a week of inactivity|
|Large||8||1024 MB||4||After a week of inactivity|
|XLarge||16||2048 MB||8||After a week of inactivity|
If your application gets archived, to reactivate the application, make a request to it. The first request will be slow, but subsequent requests will respond with normal speed.
Note that each container your application runs on costs a certain number of points. To see how many points you have used and are allocated, or to see which containers your application is using, execute the
appc cloud list command.
Currently, API Runtime Services only supports applications opening one server listening port. There cannot be more than one TCP/HTTP server started in one application.