Install for Development

There are a number of ways to start working with an instance of the Realm Object Server. Typically, we recommend using our Cloud to try out the Platform and for development usage. If you have requirements which don't allow this, you can also install the server locally. We recommend the Quick-Start install for users who may be new to NPM and Node. For users who are familiar with these technologies, it is often preferred to use the Manual Install.

Getting a Cloud Instance

Getting a hosted instance of the Realm Object Server is as easy as heading over to our cloud landing page and signing up.

Once you've signed up, you'll create a new instance from our instances management page.

Quick Start Install

This will install a number of items like NVM, Node, NPM at a global level. If you have existing installations, they may potentially be upgraded / downgraded. If this is an issue, please use our manual install

The simplest method of installation is by using our install script, which will resolve all prerequisites for you:

curl -s https://raw.githubusercontent.com/realm/realm-object-server/master/install.sh | bash

Manual Install

Prerequisites

To get started, please ensure you have Node installed on your machine. Instructions are available here and we recommend using NVM.

Ubuntu
macOS
RHEL/CentOS
// Ubuntu 16.04 (64 bit; 32-bit is not supported)
//It is recommended that you install the server as a normal user.
sudo apt-get update
sudo apt-get install build-essential libssl-dev
sudo apt-get install python
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.4/install.sh | bash
// Force current session to know changes or logout and log back in
source ~/.profile
nvm install --lts
npm install -g node-gyp
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.4/install.sh | bash
nvm install --lts
npm install -g node-gyp
//Install Node.js LTS
curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -
sudo yum -y install nodejs
//To compile and install native addons from npm
sudo yum install gcc-c++ make

Install the Server

npm install -g realm-object-server

This will install the server globally which is the easiest way to try it out since it includes a CLI. For Linux, if you are installing as root (not recommended), you may need to add --unsafe-perm to the npm install commands.

Start the Server

Realm Object Server is a Node package which requires a Node project to run within. To make it easy to get going, the installation includes a command-line interface to bootstrap a project for you!

Create a new ROS project instance:

ros init my-app

This creates a Typescript-based Node project for you. Later on you can explore customizing it but for now simply start the server with defaults by:

If you have trouble running a ros command it may be due to your version of NVM. Try running nvm use 8 in your terminal.

1) Add your feature token:

Starting with Realm Object Server 3.5.0, a feature token is required to run the server. You can get your own feature token here.

From inside of your project folder, you'll need to open the index file which can be found at src/index.tsYou'll need to paste in your feature token as shown below:

import { BasicServer, FileConsoleLogger } from 'realm-object-server'
import * as path from 'path'
const server = new BasicServer()
server.start({
// ..
featureToken: '<INSERT YOUR FEATURE TOKEN HERE>',
//....
})

2) Start the server

cd my-app/
npm start

That’s it! You now have a functioning Realm Object Server running locally on port 9080! The server is tied to your terminal window for now and can be stopped by pressing Ctrl-C.

Click here for more information on the command-line interface for ROS.

Running the server via Docker

For users who need to run on Windows for development purposes, Docker can be used though we ultimately recommend moving to a Linux environment when ready for production.

We have a prebuilt docker image which can be run like so:

docker pull realm/realm-object-server
##make sure to input your own feature token
docker run -it --rm -p 9080:9080 -e SYNC_WORKER_FEATURE_TOKEN="[FEATURE_TOKEN]" realm/realm-object-server

To customize your docker deployment (adding special auth, GraphQL, etc), you may see the following guide for creating your own Dockerfile.

Upgrade the Server in Development

Upgrading the server is as simple as running an NPM install command within your ROS project

#specify specific version after the @
npm install realm-object-server@latest

Troubleshooting a failed installation

Having issues with your installation? We're here to help. Please contact us via our support channel. If possible, include the following information:

  • Steps that you followed during the installation

  • Relevant error messages and/or logs

  • Versions of NPM and Node

  • Operating system information

Going into Production

It is strongly advised that you do not enter production with a single node instance of the Realm Object Server. If you are getting ready to deploy your application to production, you will want to head over to the following section where we cover our cluster deployment that utilizes Kubernetes and Helm.

Not what you were looking for? Leave Feedback