So you’ve got your RealityServer release email and downloaded everything but how do you install it? This article will take you through the steps in setting up RealityServer on Windows or Linux as well and also provide an overview of the RealityServer directory structure. We’ll also cover how to setup your licensing.
RealityServer is provided as a set of downloadable files. The main components you will receive links to in your release email are the following.
All of these are provided in a simple archive (.tgz for the RealityServer parts, .zip for Iray Viewer) and there are no installers. Basically you just extract to your favourite location and run. We currently support 64-bit Windows and Linux operating systems only.
For the RealityServer Extras, these should be extracted to where ever you chose to extract RealityServer. The Extras archive does not contain a top level directory so you need to extract it inside your RealityServer directory.
If you are running on Windows and need a program to extract .tgz files then both WinRAR and 7-Zip are able to do this. RealityServer releases have the following version format.
rsws-{major}{minor}-{branch}.{build}.tgz
When reaching out to migenius for help, ensure you include information about what RealityServer version you are running.
To get the most out of RealityServer you’ll want to run it on a machine with a relatively modern NVIDIA GPU. The better the GPU the faster your rendering will be. You can see comparisons of GPU and cloud provider performance on our Benchmarks page.
While RealityServer can run on a CPU only machine, we don’t recommend it for anything other than reading the documentation of doing development where you don’t need to perform a lot of rendering. Even a modest but modern GPU will give a big jump in performance. Of course, then there is the cloud.
If you are wanting to test on AWS then we have a guide for Running RealityServer on AWS to help. This also includes instructions for setting up RealityServer as a systemd service on Linux which you might find useful even locally.
On Nimbix we currently offer a pre-configured application for RealityServer which you can run in their PushToCompute platform. Azure and Google Compute Engine also support GPUs and we have tested RealityServer there. Newer players like Scaleway and Linode have also recently entered the GPU cloud market.
Where ever you choose to run RealityServer, it is vitally important that you are running the most up to date NVIDIA drivers for your GPU. This has become especially important with the introduction of RTX. You can find the latest NVIDIA drivers here.
We’ve found that on some GPU models such as the Tesla range on Linux, you need to install the driver recommended for Quadro to obtain the needed version. Under Windows the drivers are specific to GPU ranges where as under Linux the drivers generally work with all GPUs.
Before starting up RealityServer you’ll need to obtain a valid license. Instructions for doing so were provided in your RealityServer release email. See the RealityServer licensing page for more details on how to install your RLM or Cloud licenses. If using a floating RLM license see this page for instructions on how to setup your license server.
Once you have extracted RealityServer to your chosen location, you can fire it up by using the included startup script. On Windows you can run or double click the realityserver.bat file, on Linux there is a realityserver file in the root directory which is a shell script that starts RealityServer. Once you’ve got it running you can navigate to the server and confirm it’s running. By default RealityServer runs on port 8080 but you can configure this in realityserver.conf. If you navigate to the server in your browser you should see something like this.
By default RealityServer just logs all of it’s output to the console. You can use the log_file directive in realityserver.conf to output this to a file instead or use redirection in your chosen shell. Here’s what the output looks like for a freshly started RealityServer.
It’s hard to stress enough how important this log output can be. You should always keep an eye on the logs while developing and if you encounter strange problems like your GPU not being used or crashes the log will almost certainly tell you something useful.
When running RealityServer in an interactive shell like this you can terminate it at any time using Ctrl+C.
One little gem (particularly if it helps solve a mystery for you) is the admin console. By default this is automatically started on port 8081. You can disable it or switch to a different port in realityserver.conf. Navigating to port 8081 on your server in your browser should give you a page like this.
As you can see the styling is pretty raw but this page contains some important information about the running RealityServer and in particular the database and its contents. You can search for the names of anything in the database and then examine the tags and scopes associated with them. This can be helpful when you are running commands that are not finding elements you think are in the database, or if you are wondering when things are loaded and unloaded from the database.
There are some important locations in your RealityServer installation which you need to be aware of. Below we’ve outlined the most important locations and what they are for.
This directory is configured in your realityserver.conf file and by default is the content_root directory included with the RealityServer release. This is where all commands expect to find files when they are referenced by filename. All paths are relative to content_root. By default the scenes subdirectory is not served by the RealityServer HTTP server but all other directories are, so don’t include anything in other directories you don’t want exposed through the HTTP server. By convention application pages hosted by RealityServer live in the content_root/applications folder but they can be put anywhere in content_root that is served by the HTTP server.
If you write your own C++ plugins for RealityServer and place them in the plugins directory they will be automatically loaded. This directory is defined in realityserver.conf with the plugin_directory directive. You can of course add your own directories if needed. Unless you are writing C++ plugins you won’t need to concern yourself with this.
Within realityserver.conf you can define various resource paths using the resources directive. You’ll find two defaults in the provided configuration for light_profiles and textures. These locations are searched when you specify a resource like a texture or .ies light profile to load but don’t specify a path. You can add more of these search paths by editing your configuration.
MDL materials are loaded from shader paths (the name a legacy from earlier times, MDL materials are not actually shaders). You’ll find a default shaders directive for the mdl directory in the default configuration as well as two conditional directives which will automatically add the system and user MDL paths if the appropriate environment variables are detected. You can add your own shader search paths, these are then included in the MDL module system.
The Server-side JavaScript V8 API stores its files in the location set in the v8 user section in your realityserver.conf. By default custom commands live in the v8/commands directory and includes in the v8/include directory. In these directories you will find the JavaScript files for the included V8 commands and includes which can be a great source of inspiration for writing your own. You can also add new V8 directories in your configuration. The include directory is searched whenever you use require() in your commands.
So you’ve now got RealityServer running, however to get the most out of RealityServer your should explore realityserver.conf and the configuration options that are available in the RealityServer Configuration documentation. There are a lot of ways you can customise RealityServer to exactly your needs in terms of directory structure, logging, security and so on. As always if you have any questions reach out to us.
Paul Arden has worked in the Computer Graphics industry for over 20 years, co-founding the architectural visualisation practice Luminova out of university before moving to mental images and NVIDIA to manage the Cloud-based rendering solution, RealityServer, now managed by migenius where Paul serves as CEO.