Running The Server

So far, we have been simulating API requests from the console. This was very convenient during our development process - It allowed us to test Ruby commands, as well as API requests, all in one place.
For a production system, our application will need to run in a server, and make the API accessible to any HTTP client.

In this section, we will go through some useful commands and tools for running your application in a server.

Running the server

Your xnlogic VM has the TorqueBox application server installed on it. The server is set up to automatically deploy your xnlogic application on startup.

In order to start the server, log in to the VM (using xnlogic ssh) and run the following command:

➜  ~  xn-server

The server will start, and print its log to the console. Once you see the following log message, the server is ready.

{ timestamp: '2015-02-21 17:44:03,625',
  level: 'INFO',
  app: 'XN',
  thread: 'ServerService Thread Pool -- 48',
  message: { initializing: [ 'admin', 'db01' ] } }

You can stop the server at any time by hitting Ctrl+C.

Note: The server log can also be found at ~/xn.dev/tmp/server.log.

Note: When using Neo4j, you cannot run the server and xn-console at the same time. This limitation is enforced by Neo4j’s architecture.

Applications and databases

Before we continue, there are a couple of basic concepts you should be familiar with:

  • A server can run multiple applications.
  • A server can run multiple instances of the same application, each with its own database.
  • In some places in the code, we use the term client to refer to an application instance.

If you followed our tutorial, your server should currently contain two application instances:

  1. my_app application that uses a database called db01.
  2. An admin application, with its own database.

A server has a single admin application that is created automatically. The admin application is used for managing all other xnlogic applications on the server.

Auth tokens

In order to send API request, you must include an auth token with your request. The auth token tells the server who you are and which application instance you want to access. Auth tokens are managed by the admin application.

In order to get an auth token for our application, we need to send an API request to the admin application. Here are the steps we’ll need to take:

First, we need an auth token that will allow us to access the admin token. We can find such a token in ~/xn.dev/user/xn_infra_admin. We can use this token to make a GET request to /is/client/report/app_tokens, and get all available tokens.

The simplest way to do that from the shell is as follows:

➜  ~  source ./xn.dev/user/xn_infra_admin

➜  ~  get /is/client/report/app_tokens
{ app_tokens: 
   [ { name: 'db01',
       app_name: 'my_app',
       api_server: 'http://localhost:8080',
       api_prefix: '/v1',
       data_location: '/opt/xn_apps/my_app/db01',
       admin_token: 'db01 Hx6NqfpaJzbWLvgGyeDm',
       authenticator_token: 'db01 SCziKzz9Y8LA7avfsTAn' } ] }

You can see the admin_token for our application in the response. Save it in the environment variable LMTOKEN, and you’re good to go.

➜  ~  export LMTOKEN="db01 Hx6NqfpaJzbWLvgGyeDm"

➜  ~  get /model/user/id/73/to/should_follow/properties/username
curl -H "Authorization: db01 Hx6NqfpaJzbWLvgGyeDm" -s 'http://127.0.0.1:8080/v1/model/user/id/73/to/should_follow/properties/username'
[ [ 75, 'randy.marsh' ],
  [ 145, 'keira.hills' ],
  [ 147, 'gregoria' ],
  [ 133, 'mateo_hirthe' ] ]

Note: The shell on the dev VM is configured with the commands get, post, put, patch and delete. These commands are used for sending HTTP requests to an xnlogic server. The hostname of the server, and the auth token, are picked up from the environment variables LM_SERVER and LMTOKEN, respectively.
For convenience, these methods also print out the curl command used for making the request.

HTTP Headers

Sending API requests from the shell is convenient, but you can use any HTTP client you like. Just make sure your request includes (at least) the following two HTTP headers:

  1. Accept: application/json
  2. Authorization : YOUR-AUTH-TOKEN

Summary

  • We can run the server using xn-server.
  • The server automatically deploys (every instance of) our application.
  • We access the server with auto tokens. An auth token tells the server who we are and which application instance we want to access.
  • We can send API requests with any HTTP client. One convenient option is using the aliases get, post, put, patch and delete from the shell.