Installation

1
Last updated 18 days ago

Realm Object Server is a Node application that is distributed via npm. To help get you started quickly, we have a few different installation options. If you are already familiar with Node and NPM, we suggest using the manual install via npm. If not, we suggest using our quick start install via our own curl script.

These instructions detail the base install which is used for getting started and basic testing. Once it is time to move into a production environment, you will want to follow our enterprise architecture guidelines to support your application at scale.

Supported Operating Systems

We currently support the following operating systems:

  • macOS 10+

  • Ubuntu 16.04+

  • RHEL 6+

  • CentOS 7+

We plan to add native support for Windows. In the meantime, you can use Docker during your development period.

Ports

The Realm Object Server utilizes websocket connections over TCP to synchronize data. This means that you will need to make sure your firewall allows TCP communication over whichever ports your ROS is configured to use. By default, this is port 9080 for HTTP traffic. We recommend securing your server by enabling HTTPs communication which is done over port 9443.

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.

Connecting to the Server

Connections to the server are made via websockets which communicate (by default) over port 9080, so you'll need to be sure to open this port. The port number can be reconfigured within your server's index file. The simplest way to test connectivity is by using Realm Studio.

Upgrading the Server

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

Running on an unsupported OS

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 -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.

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 our enterprise architecture documents. We strongly recommend using our cluster deployment that utilizes Kubernetes and Helm for the best experience.

Not what you were looking for? Leave Feedback