Realm Platform 1.x Walkthrough

Getting started with the full Realm Platform, both the Realm Database and the Realm Object Server, can seem intimidating, but in truth, it’s pretty straightforward. In this article, we’ll walk you through downloading, installing, and configuring the Realm Object Server on Amazon Web Services, using either Realm’s AMI or an Ubuntu Linux instance, then through building a small iOS application backed by the Object Server for multi-user support.

Next, we’ll cover upgrading to the Professional Edition (and why you might want to), and cover another way to do server-side programming with Event Handling. And, finally, we’ll cover Enterprise Edition features, including synchronous backup and manual failover.

NOTE: This Technote only addresses the 1.x version of Realm Platform, not the newest 2.0 version.

Realm Platform overview

The core concept of the Realm Platform is a lightweight object container called a Realm. Like a database, data in Realms can be queried and filtered, interconnected, and persisted. Unlike a traditional database, though, objects in Realms are live and fully reactive. Realms synchronize seamlessly between devices and applications, and can be accessed safely across threads.

The Realm Database is built from the ground up to run on mobile devices. Unlike a traditional database, objects in a Realm are native objects. You don’t have to copy objects out of the database, modify them, and save them back—you’re always working with the “live,” real object. If one thread or process modifies an object, other threads and processes can be immediately notified. Objects always stay in sync.

Applications built on the Realm Platform have the ability to access and create Realms on the Realm Object Server. All your application needs is the connection information for your Object Server and the URLs of the server-side Realms. Objects on the Realm Object Server will be downloaded as the application needs them—then the local copy of the Realm will be kept fully synchronized with the Object Server’s copy.

A key concept of the Realm Platform is the use of multiple Realms: your application isn’t tied to a single data source, and data sources are as easy to access as web pages. Realms offer fine-grained access control tied to user accounts. A Realm on the Object Server can be public, accessible to all users (for instance, a catalog for an online store); private, accessible to only the user who created it (for instance, a private task list, or application settings); or shared between specific users (for instance, a household shopping list).

Installing Realm Developer Edition on AWS

While this tutorial only covers installing on Amazon Web Services, you can also install the Realm Object Server from the Azure Marketplace, Digital Ocean, or on your own Linux or macOS server. Read Install Realm Object Server for full details!

We provide public Amazon Machine Images (AMIs) for the Realm Platform, using hardware virtual machine (HVM) virtualization based on Ubuntu 16.04. If you’re already running an Ubuntu, Red Hat Enterprise, or CentOS AMI, you can install Realm Developer Edition from Realm’s PackageCloud repository.

Installing the Developer Edition AMI

From the EC2 console, click AMIs under Images in the sidebar. Select your preferred region from the top menu bar on the right, and search for one of the following images:

Region Image AMI ID
ap-northeast-1 (Tokyo) ami-a03233c7
eu-west-1 (Ireland) ami-aecfdec8
us-east-1 (N. Virginia) ami-8a62289c

Select the image and click Launch. On the next screen, “Choose an Instance Type,” select an instance type. You can leave the default, t2.micro, selected to stay on the free tier, although we recommend m3.medium. Click Review and Launch.

Finally, click Launch. You’ll be prompted to select an existing public/private key pair for SSH access or to create a new one. After the instance is launched, click View Instance. The dashboard will now show your running instance with its public IP address.

Using Amazon’s instructions, you should be able to connect to your AMI now with SSH. You’ll need the copy of the private key you created when you launched the instance. On your local machine, open a terminal/console window and move your .pem (private key) file to your ~/.ssh directory, then specify it when you SSH to your instance:

mv ~/Downloads/aws.pem ~/.ssh/aws.pem
chmod 400 ~/.ssh/aws.pem
ssh -i ~/.ssh/aws.pem aws-instance-name.amazonaws.com

Use your own private key filename, path, and AWS name for the commands. (If you’re on a Mac, ~/Downloads/ is the default download directory for most web browsers, but it will be different on Linux.) After you run the first two commands, you’ll only need the ssh command to log in again.

While the Realm instance has port 22 (SSH) open by default, you’ll need to open up some more ports for the Realm Object Server: 9080 (Realm Studio and client access) is essential, and you may also need 7800 (sync workers), 27810 (backup workers), and if you’re using statsd for monitoring, 8125. Click on the instance’s security group and click on Edit inbound rules. Add a Custom TCP rule for port 9080, allowing 0.0.0.0/0 for all IPs, or alternatively an IP address range to limit connections to. You can add other rules for other important ports, or you can specify a range of ports in one rule (e.g., 22-9999), although doing so is less secure than opening only specific ports.

Once this rule is in place, you should be able to use Realm Studio to manage this instance at <ip-address>:9080.

Installing on an existing Linux AMI instance

Realm maintains package repositories through a service called PackageCloud; installing and starting Realm Object Server takes just a few steps.

Note: these instructions, and the rest of this tutorial, assume you’re running Ubuntu Linux on all your servers. You’ll need to use the yum package manager under RHEL or CentOS; read the Linux installation guide for more details.

  1. SSH into your instance.

  2. Install the Object Server from Realm’s PackageCloud repository. On Ubuntu, type:

    curl -s https://packagecloud.io/install/repositories/realm/realm/script.deb.sh | sudo bash
     sudo apt-get update
     sudo apt-get install realm-object-server-developer

    On RHEL/CentOS, type:

    curl -s https://packagecloud.io/install/repositories/realm/realm/script.rpm.sh | sudo bash
     sudo yum -y install realm-object-server-developer
  3. Start the Realm Object Server. On RHEL/CentOS version 6, type:

    sudo chkconfig realm-object-server on
     sudo service realm-object-server start

    On Ubuntu or RHEL/CentOS version 7, type:

    sudo systemctl enable realm-object-server
     sudo systemctl start realm-object-server

Lastly, you’ll need to make sure that port 9080 is open on your AMI instance, as this is used for Realm clients and Realm Studio. You may also need 7800 (sync workers), 27810 (backup workers), and if you’re using statsd for monitoring, 8125. Click on the instance’s security group and click on Edit inbound rules. Add a Custom TCP rule for port 9080, allowing 0.0.0.0/0 for all IPs, or alternatively an IP address range to limit connections to. You can add other rules for other important ports, or you can specify a range of ports in one rule (e.g., 22-9999), although doing so is less secure than opening only specific ports.

Once this port is open, you should be able to manage ROS using Realm Studio at <ip-address>:9080.

Realm Studio

Once your AMI is set up, you can open up Realm Studio, and select “Connect to Realm Object Server.” In the URL field, enter <ip-address>:9080, and press Connect, as your server will now be running with a default realm-admin account, and no password. Once you login, press the User tab, select the realm-admin user, and press the “Change Password” button.

Realm Studio gives you the following features:

  • Realms: Paths, permissions, and owners of Realms synced to this Object Server, with the ability to “drill down” and display the models and contents of individual Realms
  • Users: User information and management for this Object Server, including granting and removing administrative privileges
  • Logs: System logs for the Object Server, with selectable detail level

Building an iOS app with RealmLoginKit

The Multi-User Tasks Tutorial walks you through building a multi-user version of RealmTasks, our canonical demo app. The tutorial will show you how to:

  • Setup a new Realm-based project from scratch using Cocoapods
  • How to adopt and setup a free Realm utility module called RealmLoginKit which allows you to easily created multi-user ready applications with almost zero coding
  • How to create a simple Realm-based Task Manager that can interoperate with the fully-featured RealmTasks that comes with the Realm Platform distribution

In order to successfully complete the tutorial, you will need a Macintosh running macOS 10.12 or later, as well as a copy of Xcode 8.2.3 or later.

For full instructions and source code, go to our GitHub repository for the tutorial:

https://github.com/realm-demos/realm-MultiUserTasksTutorial

Upgrading to Professional Edition

Your PE or EE license also enables you to use the Realm Sync binding for Node.js outside of the Realm Object Server, enabling the Event Handling, Data Access and Data Connector features.

You could use it to enable distributed event handling that responds to data changes in a more performant way, or you could use it to interact with the Realm Object Server from your existing servers, enabling you to push data to the Realm Object Server instead of simply reacting to data that arrives on the Realm Object Server.

To get a free 14-day trial of the Realm Platform Professional Edition, fill out this form. We’ll send you an access token in email.

After you’ve gotten the access token, you can proceed. First you’ll stop and uninstall the Developer Edition, keeping the data in the Realms intact, then install the Professional Edition. This work can be done from the Unix shell prompt on your server.

SSH to the server running Realm Object Server, and type the following commands. (Lines beginning with # are comments and don’t need to be entered.)

# Stop the service before uninstalling
sudo systemctl stop realm-object-server

# Uninstall the Deeloper Edition
sudo apt-get remove realm-object-server-developer

# Set up your new Professional Edition token
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Set up the new package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.deb.sh | sudo bash
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-object-server-professional

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

You should be able to access this instance using the same IP address and port within Realm Studio, allowing you to manage Realms and users that are synced to it.

Create an event handler

To use Realm Event Handling, you’ll need to create a small Node.js application that watches for changes being synced to the Realm Object Server, and then reacts to the changes by calling an external natural language processing API called Wit.ai. The code will have the effect of adding datetime reminders to your tasks.

First, create a directory to place the server files, then create a file named package.json. This JSON file is used by Node.js and NPM, its package manager, to describe an application and specify external dependencies.

You can create this file interactively by using npm init. You can also fill in a simple skeleton file yourself using your text editor. You can copy and paste this into your package.json file for our Realm Tasks example:

{
  "name": "RealmTasks",
  "version": "0.0.1",
  "description": "Use Realm Object Server's event-handling capabilities to add datetime reminders to your tasks.",
  "main": "index.js",
  "author": "Realm",
  "dependencies": {
    "realm": "^1.8.2",
    "node-wit": "4.2.0"
  }
}

After the package.json file is configured properly, type:

npm install

to download, unpack and configure all the modules and their dependencies.

Your event handler will need the access token from Wit.ai as well as two Realm access tokens: one of them is the one that you received in email to enable the Enterprise Edition; the other is the Object Server’s “admin token,” which lets your application log in as an admin user. On the Object Server’s server instance, you can view the token with:

cat /etc/realm/admin_token.base64

Now that you’ve set up everything you need, you can create the file where the event handling code lives. Copy this into a new file called index.js, and add in the tokens where indicated:

'use strict';

var fs = require('fs');
var Realm = require('realm');
const {Wit, log} = require('node-wit');

// Professional or Enterprise Edition access token, from your email
var token = "INSERT_YOUR_ACCESS_TOKEN";
Realm.Sync.setFeatureToken(token);

// Realm admin token
var REALM_ADMIN_TOKEN = "INSERT_YOUR_ADMIN_TOKEN";

// Server access token from wit.ai API
var WIT_ACCESS_TOKEN = "INSERT_YOUR_WIT_TOKEN";

// The URL to the Realm Object Server
var SERVER_URL = 'realm://YOUR_SERVER_URL:9080';
// var SERVER_URL = 'realm://127.0.0.1:9443'; // if it's local

// The path used by the global notifier to listen for changes across all
// Realms that match.
var NOTIFIER_PATH = ".*/realmtasks";

const client = new Wit({accessToken: WIT_ACCESS_TOKEN})

function isRealmObject(x) {
    return x !== null && x !== undefined && x.constructor === Realm.Object
}

var change_notification_callback = function(change_event) {
    let realm = change_event.realm;
    let changes = change_event.changes.Task;
    let taskIndexes = changes.modifications;

    console.log(changes);

    // Get the task objects to processes
    var tasks = realm.objects("Task");

    for (var i = 0; i < taskIndexes.length; i++) {
        let taskIndex = taskIndexes[i];
        // Retrieve the task object from the Realm with index
        let task = tasks[taskIndex];
        if (isRealmObject(task)) {
            console.log("New task received: " + change_event.path);
            // get date from wit.ai
            // node-wit: https://github.com/wit-ai/node-wit
            const client = new Wit({accessToken: WIT_ACCESS_TOKEN});
            client.message(task.text, {}).then((data) => {
                console.log("Response received from wit: " + JSON.stringify(data));
                var dateTime = data.entities.datetime[0];
                if (!dateTime) {
                    console.log("Couldn't find a date.");
                    return;
                }
                console.log("Isolated calculated date: " + dateTime.value);
                // to write the date, we'll have to add a date property on the client and migrate it
                realm.write(function() {
                    task.date = new Date(dateTime.value);
                });
            })
            .catch(console.error);

            // to write the date, we'll have to add a date property on the client and migrate it
            // realm.write(function() {
            //     task.date = ;
            // });

          }
    }
};

//Create the admin user
var admin_user = Realm.Sync.User.adminUser(REALM_ADMIN_TOKEN);

//Callback on Realm changes
Realm.Sync.addListener(SERVER_URL, admin_user, NOTIFIER_PATH, 'change', change_notification_callback);

console.log('Listening for Realm changes across: ' + NOTIFIER_PATH);
// End of index.js

This code uses regex to watch for changes in any user subdirectories named realmtasks. The pattern is defined as NOTIFIER_PATH, and uses the .* wildcard pattern to indicate it’ll watch all user directories.

After defining some initial tokens, variables, and functions, we define change_notification_callback, which will be run whenever a change happens in Realms covered by NOTIFIER_PATH. Inside this callback, we will look for updated Task objects in these Realms, call Wit.ai with the text of the Task, and update its date property if it returns a datetime object. Finally, at the end of the event handling script, we have code that authorizes an admin user to listen to changes on all realmtasks Realms.

To run the code above, just start node in the same folder as the index.js file:

node index.js

Finally, if you’d like to make your node process a little more bulletproof, you can use a process manager like PM2, so that it will run and automatically restart the event handler in case of a crash.

Upgrading to the Enterprise Edition

To upgrade, you’ll need to contact us to get a demo access token. First you’ll stop and uninstall the Realm Object Server Professional Edition, keeping the data in the Realms intact, then install the Enterprise Edition. This work can be done from the Unix shell prompt on your server.

SSH to the server running Realm Object Server, and type the following commands. (Lines beginning with # are comments and don’t need to be entered.)

# Stop the service before uninstalling
sudo systemctl stop realm-object-server

# Uninstall the Professional Edition
sudo apt-get remove realm-object-server-professional

# Set up your new Enterprise Edition token
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Set up the new package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-object-server-enterprise

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

You should be able to browse to the same IP address and port using Realm Studio and the same admin account to view the Realms you created previously in this walkthrough.

Adding sync workers

The sync worker is the process that stores Realms, responds to Realm mobile clients, and merges changes with Realm’s conflict resolution algorithm. The Enterprise Edition of the Realm Object Server comes with a sync worker installed on the server in the default configuration file. In some cases you may want to separate the sync workers from the Realm Object Server, which handles the authentication and routing of incoming realm mobile client requests, for security, fault tolerance, and load separation concerns. Let’s add an additional sync worker to our architecture.

The first thing you need to do is spin up a new EC2 instance for your new sync worker. Follow the instructions at the beginning of this walkthrough and SSH to the new instance, then install the realm-sync-worker package from Packagecloud.

# Set up the Enterprise Edition token
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Set up the new package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash
sudo apt-get update

# Install the Sync Worker
sudo apt-get install realm-sync-worker

# Enable and start the service
sudo systemctl enable realm-sync-worker
sudo systemctl start realm-sync-worker

Now, the sync worker is installed on a separate host. We need to edit the Realm Object Server’s configuration file to connect to the new sync worker. SSH back to the Realm Object Server’s instance, and open /etc/realm/configuration.yml in your favorite text editor.

Find the Sync section, uncomment the following lines, and add the internal DNS or IP address of your newly created server.

# /etc/realm/configuration.yml

sync:
  servers:
    - id: '0'
    address: '<internal DNS or IP of sync worker server>'
    port: 7800

The underlying IP address of the sync-worker can change as long as the ID of the sync worker remains the same, so in a failover scenario–bringing a new sync-worker online because an existing one has failed–you can just keep the ID value and spin up the new worker. In fact, if you use a DNS name, you could simply update your name server to point to the sync worker’s new address in the event of failure. For more information, read the Failover documentation.

Now that you’ve edited the configuration file, restart the Object Server. At the shell prompt:

systemctl restart realm-object-server

If you look at your system logs right now, you’ll see errors:

[syncProxy] internal error: Error: connect ECONNREFUSED

This is because we haven’t configured the sync worker to listen to the connection yet. We’ll do that in a moment, but there’s one other thing to do while on the Object Server’s machine: you’re going to need to copy its public key. This file is stored in /etc/realm/token-signature.pub. This file needs to match on both the sync worker and Object Server. You can copy the file using scp:

scp /etc/realm/token-signature.pub sync-worker-ip:/etc/realm/token-signature.pub

(Replace sync-worker-ip with the actual IP address or DNS name of the sync worker machine.) You can also use FTP to transfer the key, or even just copying the public key on the Object Server machine to your clipboard and pasting it into /etc/realm-token-signature.pub on the sync worker.

Now, let’s SSH back to the sync worker, and edit its configuration file, /etc/realm/sync-worker-configuration.yml, to uncomment the sync section in its network block:

# /etc/realm/sync-worker-configuration.yml

network:
    sync:
        listen_address: '0.0.0.0'

Note that 0.0.0.0 listens on all network interfaces; in practice, it’s more secure to specify the actual IP of the Realm Object Server.

Now, finally, restart the sync worker.

systemctl restart realm-sync-worker

You can follow this process to add more than one sync worker, spreading out the load for horizontal scaling.

Adding backup clients

For fault tolerance, you will want to regularly backup the realm data in the event of system failure or outage. Realm provides a continuous backup feature where each changeset synced to the sync worker is sent to the backup client.

To set up a backup client, the process is similar to setting up a sync worker:

# Set up the Enterprise Edition token
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Set up the new package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash
sudo apt-get update

# Install the Sync Worker
sudo apt-get install realm-object-server-backup-client

Edit the backup client’s configuration file before starting it:

# /etc/realm/object-server-backup-client.yml

sync:
  servers:
    - id: '0'
    address: '<internal DNS or IP of sync worker server>'
    port: 7800

Now, start the client:

# Enable and start the service
sudo systemctl enable realm-object-server-backup-client
sudo systemctl start realm-object-server-backup-client

Finally, SSH to the sync worker and uncomment/modify its listen_address line:

# /etc/realm/sync-worker-configuration.yml

network:
    sync:
        listen_address: '0.0.0.0'

Restart the sync worker.

systemctl restart realm-sync-worker

The backup client now has the full data set of all Realms set to the sync worker.

As a best practice, you should prepare to fail over to the backup client and start a sync worker on it so it can take over for a sync worker. To do this, you should pre-install the sync worker on the backup client without starting it. SSH to the backup client.

sudo apt-get install realm-sync-worker

Edit the configuration of the sync worker so it starts reading Realms from the same folder that the backup client is saving them to.

# /etc/realm/sync-worker-configuration.yml

# change the root_path to point to the backup client folder
storage:
  root_path: '/var/lib/realm-object-server-backup-client'

# uncomment and correctly set the listen_address line
network:
  sync:
    listen_address: '0.0.0.0'

Now, in the event your original sync worker fails, you will be ready for failover by simply stopping the backup client process and starting the sync worker you have prepared.

sudo systemctl stop realm-object-server-backup-client
sudo systemctl start realm-sync-worker

For more details, read Failover in the Professional/Enterprise Edition documentation.

After failing over, you’ll need to start a new backup client that points to this server, perhaps triggered automatically through your tooling (e.g., an Auto Scaling Group resource that sends CloudFormation event notifications).

Adding a monitoring system

Now let’s dive into the day two operations bits. First, we’ll set up a monitoring system and integrate it with our Realm distributed system. Realm uses statsd endpoints for metrics. This guide will describe setting up a server with Grafana and InfluxDB, but you can use any statsd compliant system.

It’s considered best practice to have a dedicated server separate from your other infrastructure. Set up a new server and SSH to it, then enter the following steps (as usual, # lines are comments):

# Let's set-up the package sources
curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/lsb-release
echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

# Update the repo
sudo apt-get update

# Install InfluxDB
sudo apt-get install influxdb

# Start Influx
sudo systemctl start influxdb

# Use the influx command line to create a database
influx
> CREATE DATABASE realmdemo

# Use the SHOW DATABASES command to see output similar to the below
> SHOW DATABASES
name: databases
name
----
_internal
realmdemo

> exit

We need to setup Telegraf on the sync worker and gather the stats to export them to our monitoring server. So, now SSH to the server with the sync worker:

# Use the Influxdb repo to set up the package sources
curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/lsb-release
echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

# Update the repo
sudo apt-get update

# Install Telegraf
sudo apt-get install telegraf

Now, open /etc/telegraf/telegraf.conf in a text editor to add the InfluxDB server and database name in the outputs.influxdb section.

[[outputs.influxdb]]
  urls = ["http://<IP_OF_MONITORING_SERVER>:8086"] # required
  database = "realmdemo" # required

We also need to add the inputs for statsd for the Realm Object Server in the same file in the inputs.statsd section:

[[inputs.statsd]]
  service_address = ":8125"

Now, enable and start Telegraf:

sudo systemctl enable telegraf
sudo systemctl start telegraf

Now that you have InfluxDB and Telegraf running, let’s set up Grafana to view the Realm data and metrics:

# Set up the Grafana repo
echo "deb https://packagecloud.io/grafana/stable/debian/ wheezy main" | sudo tee /etc/apt/sources.list.d/grafana.list
curl https://packagecloud.io/gpg.key | sudo apt-key add -

# Update the repo
sudo apt-get update

# Install Grafana
sudo apt-get install grafana

# Enable and start Grafana
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

Now let’s browse to the Grafana server in a web browser by going to port 3000 of the monitoring server’s public IP. The default login is admin/admin.

Then, click Add a Data Source and fill in the information for InfluxDB:

Now, you can select New Dashboard and start adding metrics to graphs. Realm-specific metrics will be prepended with realm_. Add Telegraf on each Realm host in your distributed system.

Consult the Realm Platform PE/EE documentation for a full list of supported metrics.

Adding a logging system

Now, let’s set up a dedicated logging server to pull logs from the various components of our Realm set-up at regular intervals. We’ll use Elasticsearch and Kibana, integrating them with Realm via the Filebeat utility.

Install Elasticsearch and Filebeat

First, set up a new server or EC2 instance to use as the logging server. Once that’s done, SSH into it:

# Clear any pre-existing Java installs
sudo apt-get remove --purge openjdk*

# Add the Oracle repo
sudo add-apt-repository -y ppa:webupd8team/java

# Update the repo and install Java and wget
sudo apt-get update
sudo apt-get -y install oracle-java8-installer
sudo apt-get install wget

Then install Elasticsearch:

# Add Elasticsearch's key and repository
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list
sudo apt-get update

# Install Elasticsearch
sudo apt-get install elasticsearch
# Enable and start Elasticsearch
sudo systemctl daemon-reload
sudo systemctl enable elasticsearch.service
sudo systemctl start elasticsearch.service

Elasticsearch is now installed and listening on port 9200 by default. Next, let’s set-up Filebeat on the Realm Object Server and Realm Sync Worker. SSH back to the sync worker machine, not the logging machine:

# Set up the Filebeat repo and install
echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list
sudo apt-get update
sudo apt-get install filebeat

Now let’s edit Filebeat’s configuration file at /etc/filebeat/filebeat.yml. This is a YAML file, so watch the indentation!

input:
      paths:
        - /var/log/realm-sync-worker.log
      tail_files: true
output:
  elasticsearch:
    hosts: ["<logging_server_hostname>:9200"]

Then, start Filebeat, so it picks up the config change:

sudo systemctl start filebeat

We also want to get the logs from our Realm Object Server, so let’s SSH to that host as well and set up Filebeat there, too:

# Set up the Filebeat repo and install
echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list
sudo apt-get update
sudo apt-get install filebeat

The changes to Filebeat’s configuration file at /etc/filebeat/filebeat.yml are similar, but just with a different log file path:

input:
      paths:
        - /var/log/realm-object-server.log
      tail_files: true
output:
  elasticsearch:
    hosts: ["<logging_server_hostname>:9200"]

Then, start Filebeat over here, too:

sudo systemctl start filebeat

Now, let’s SSH back to the logging server. We need to set up Elasticsearch for the incoming Filebeat connections. Edit its configuration file at /etc/elasticsearch/elasticsearch.yml and edit its network.host block:

network.host: '0.0.0.0'

Finally, restart Elasticsearch:

sudo systemctl restart elasticsearch

Install Kibana

Kibana is another product from Elasticsearch that lets us visualize the logs and provides a UI.

SSH back to the logging server. (We’re almost done with the SSH hopping, we promise.)

The Elasticsearch package repository is already set up, so installing it over here is pretty easy:

sudo apt-get update
sudo apt-get install kibana

# enable and start the service
sudo systemctl enable kibana
sudo systemctl start kibana

Now, let’s login to our Kibana server! Go to http://<logging_server_hostname>:5601 in a web browser. The Kibana configuration page will open. Create an index pattern with the name filebeat-*, and enter @timestamp as the Time-field name:

Now, you can go to the Discover tab, and select a recent time interval, such as the last 15 minutes. Start generating some connections to the Realm Object Server, and you should start to see Kibana populating with logs:

Summing up

We’ve shown you how to start and deploy the Realm Platform, integrate it into your apps to enable syncing and logins, add server-side Functions and event handling, and add additional sync workers and backup clients. We’ve covered the full depth of Enterprise Edition features, and you can return to this document whenever you need to a quick reference for your future projects.

Good luck with your development work! Feel free to contact your representative at Realm any time you need help.