This guide is a full reference for configuring your RAD Server instance. It was written by Eli M. and is part of the collection of New RAD Server (EMS) Articles, Resources, and eBook.
How-To:
Configuring Your RAD Server Instance
RAD Server is a turn-key application foundation for rapidly building and deploying service based applications. RAD Server provides automated Delphi and C++ REST/JSON API publishing and management, enterprise level database integration middleware, IoT Edgeware and an array of application services such as User Directory and Authentication services, Push Notifications, Indoor/Outdoor Geolocation and JSON data storage.
There are a number of sections in the RAD Server configuration file
- Locating the RAD Server Configuration File
- Configuring Database Connections [Data]
- Configuring Server Limits [Server.Limits]
- Configuring Server Authentication [Server.Keys]
- Configuring Custom Resource Modules [Server.Packages]
- Configuring Push Notifications [Server.Push]
- Configuring User and Group Permissions [Server.Authorization]
- Setting Resource Redirects [Server.Redirect]
- Configuring a Proxy [Server.EdgeHTTP]
- Enabling Multi-tenancy [Server.Tenants]
- Configuring The Server Root Path [Server.Roots]
- Configuring Public Paths [Server.PublicPaths]
- Configuring Dev Server Connections [Server.Connection.Dev]
- Configuring API Cross Domain Headers [Server.APICrossDomain]
- Configuring Dev Server Threads [Server.Threads.Dev]
- Configuring Console Logins, Cookies, And Display Options [Console]
- Configuring Dev Console Connections [Console.Connection.Dev]
- Configuring Console Browser Settings [Console.Browser]
- Configuring Console Paths [Console.Paths.*]
Let’s jump right in.
Locate the RAD Server Configuration File
The RAD Server configuration file is usually located at C:\Users\Public\Documents\Embarcadero\EMS\emsserver.ini on Windows or /usr/lib/ems/emsserver.ini on Linux. It is a text file that is readable and writable with the TMemIniFile class. Configuring the database connection, the EMS Server, and the EMS Console are a few of the configuration sections available.
Configuring Database Connections [Data]
Configuring Database Connections [Data]The Data section is where you can configure the connection to your RAD Server Database (powered by InterBase). The Server prefixed sections are where you can configure the settings of EMS Server. These sections are Server.Limits, Server.Keys, Server.Connection.Dev, Server.APICrossDomain, Server.Threads.Dev, Server.Packages, Server.Push.GCM, Server.Push.APNS, Server.Authorization, Server.Redirect, Server.EdgeHTTP, Server.Tenants, Server.Roots, and Server.PublicPaths. The Console profixed sections are where you can configure the settings of EMS Console. These sections are Console.Login, Console.Cookies, Console.DisplayOptions, Console.Connection.Dev, Console.Browser, Console.Paths.Dev, Console.Paths.ISAPI, and Console.Paths.Apache.
In the Data section there are the RADServer Database (powered by InterBase) connection parameters in the form of InstanceName and Database. InstanceName could be blank or it could point to a local or remote database like localhost/gds_db or remote_host/gds_db. You can use InterBase Manager to locate the instance name of your RAD Server Database. For more information about connecting to a remote RAD Server Database (powered by InterBase) take a look at Accessing Remote Databases in the Embarcadero DocWiki. Multiple physical installs of RAD Server should be able to all use the same remote RAD Server Database (powered by InterBase) backend via the InstanceName setting.
The Database setting is set to C:\Users\Public\Documents\Embarcadero\EMS\emsserver.ib by default on Windows. The UserName and Password for connecting to the RAD Server Database (powered by InterBase) default to sysdba and masterkey. The SEPassword parameter is for connecting to an encrypted database. Connection pooling is enabled by default using the Pooling setting. And finally the maximum amount of pooled connections is controlled by the PooledMax setting which defaults to 50.
[Data] ;# InterBase connection parameters InstanceName= Database=C:\Users\Public\Documents\Embarcadero\EMS\emsserver.ib UserName=sysdba Password=masterkey SEPassword= ;# SEPassword connects to an encrypted database Pooled= ;# Set Pooled=0 to disable connection pooled, Pooled=1 to enable. Default value is 1. PooledMax= ;# Set PooledMax=10 to limit maximum pooled connection. Default value is 50.
Configuring Server Limits [Server.Limits]
The first two sections of the configuration for the server itself in RAD Server and Server.Limits and Server.Keys. Server.Limits allows you to configure the maximum amount of concurrent HTTP requests through the MaxConnections setting which defaults to 32. It also allows you to set the maximum amount of users in the RAD Server EMS database through the MaxUsers setting.
[Server.Limits] MaxConnections= ;# Set MaxConnections=10 to limit maximum concurrent HTTP requests. Default is 32. MaxUsers= ;# Set MaxUsers=3 to limit the number of users in the EMS database. This value is only used ;# when less than the maximum users permitted by the EMS runtime license.
Configuring Server Authentication [Server.Keys]
Server.Keys allows you to set a number of server side connection settings like a MasterSecret, an AppSecret, and an Application ID. The MasterSecret setting is a string that allows you to bypass the permissions which have been setup in the Server.Authorization section. By default it is blank (off). The AppSecret setting is a string that when set will allow any request to the endpoints that are authorized. Lastly, the ApplicationID is also a string that identifies a RAD Server and lets you differentiate between RAD Servers. If the ApplicationID that the client sends to the server does not match the ApplicationID on the server the request is rejected. All three settings can be passed to the server in your HTTP client request as headers. For more information about these three settings check out Editing the Configuration of Your EMS Server Manually in the DocWiki.
[Server.Keys] MasterSecret= ;# MasterSecret may be blank. If blank then the EMS server will not support ;# MasterSecret authentication. ;# HTTP 401 (Unauthorized) is raised if a request contains an incorrect MasterSecret AppSecret= ;# AppSecret may be blank. If AppSecret is not blank all requests must include the AppSecret. ;# HTTP 401 (Unauthorized) is raised if a request does not contain a correct AppSecret ApplicationID= ;# ApplicationID may be blank. If ApplicationID is not blank, all requests must include the ApplicationID. ;# HTTP 404 (not found) is raised if a request does not contain a correct ApplicationID
Configuring Custom Resource Modules [Server.Packages]
The most important settings section and probably the section you may configure frequently is the Server.Packages section. This section is where you add your own custom resource modules. During debugging the current project’s custom resource module is passed as a parameter to RAD Server and used automatically. However, for deployment you will need to add your custom resource modules in this section. It is a bit different from the other sections as it is basically a name=value list where you are setting both the name and the value. The path and filename to your custom resource module gets written first as the name and then you can add an optional description for your custom resource module as the value after the equal sign. Under Windows the filename will be to a BPL file while under Linux the filename will be to a SO file. You can also comment out lines in the list by adding a ; character before the name=value pair.
[Server.Packages] ;# This section is for extension packages. ;# Extension packages are used to register custom resource endpoints ;c:\mypackages\basicextensions.bpl=mypackage description ;/usr/lib/ems/bplProject1.so=mysample project1
Configuring Push Notifications [Server.Push]
RAD Server supports sending push notifications through both GCM (Google Cloud Messaging) and APNS (Apple Push Notification Service). The configuration for both of these are available in the Server.Push.GCM section and the Server.Push.APNS section. The only configuration option for GCM is an ApiKey setting which you will retrieve from Google and add here to be able to send push notifications to an Android device. For APNS there are three settings which are CertificateFileName, CertificatePassword, and ProductionEnvironment. In order to send APNS push notifications to an iOS device you will need to enter the path to a .p12 or .pem file and enter a certificate password if it is needed. For a production environment you should set the Server.Push.APNS ProductionEnvironment setting to 1 when your CertificateFileName has been created for production otherwise the default is 0 for a development CertificateFileName.
[Server.Push.GCM] ;# This section is for Google Cloud Messaging (GCM) settings. ;# These settings are needed to send push notificatons to an Android device ApiKey= [Server.Push.APNS] ;# This section is for Apple Push Notification Service (APNS). ;# These settings are needed to send push notificatons to an IOS device CertificateFileName= ;# Name of .p12 or .pem file CertificateFilePassword= ;# Password of certificate file. Leave blank if file does not have a password. ProductionEnvironment= ;# Set ProductionEnvironment=1 when the certificate has been created for production. ;# Set ProductionEnvironment=0 when the certificate has been created for development. ;# Default value is 0 (development).
Configuring User and Group Permissions [Server.Authorization]
The Server.Authorization section in the configuration file allows you to set specific user based and group based permissions on custom resource modules and specific endpoints within RAD Server. This section is a name=value list similar to the Server.Packages section except that the value section of the name=value list here consists of a JSON string. Endpoints inherit their parent’s public/private setting but can be overridden individually. You can set an API endpoint to be public or private using {“public”: true} and {“public”: false} as the value. In addition to public and private you can set an API endpoint to only be accessible by a specific user, all users, or all of the users in a specific group or groups. There are a number of examples in the Server.Authorization section which you can look at. For a production environment you should customize this section to configure appropriate access controls for your application. The MasterSecret setting from the Server.Keys section allows a client to bypass the Server.Authorization permissions.
[Server.Authorization]
;# This section is for setting authorization requirements for resources and endpoints.
;# Authorization can be set on built-in resource (e.g.; Users) and on custom resources.
;# Note that when MasterSecret authentication is used, these requirements are ignored.
;# Resource settings apply to all endpoints in the resource.
;# Endpoint settings override the settings for the resource.
;# By default, all resource are public.
;# Settings are specified in JSON.
;# JSON attributes
;# {"public": true} - any client is authorized
;# {"public": false} - a client may be authorized depending on user or group. user credentials (sessionid) must passed in the request
;# {"users": ["username1", "username2"]} - authorize a user by username.
;# {"users": ["userid1", "userid2"]} - authorize a user by userid.
;# {"users": ["*"]} - authorize any user.
;# {"groups": ["groupname1", "groupname2"]} - authorize a user in a user group.
;# {"groups": ["*"]} - authorize a user in any user group
;#
;# Examples
;#
;# Make all methods in the resource "Users" private except for LoginUser and SignupUser endpoints
;Users={"public": false}
;Users.LoginUser={"public": true}
;Users.SignupUser={"public": true}
;#
;# Make all methods in the custom resource "Resource1" available to users in group1
;Resource1={"groups": ["group1"]}
;#
;# Make all methods in the custom resource "Resource2" available only with MasterSecret authentication
;Resource2={"public": false}
;#
;# Special rules for user and group creators.
;# The creator of user is automatically authorized for the following endpoints:
;# Users.GetUser, Users.UpdateUser, Users.DeleteUser
;# The creator of a group is automatically authorized for the following endpoints:
;# Groups.GetGroup, Groups.UpdateGroup, Groups.DeleteGroup
Setting Resource Redirects [Server.Redirect]
The Server.Redirect section allows you to redirect one resource to another resource. For example, if you would like to install your own custom login and user system endpoints you can redirect the Users endpoints to one of your own custom resource modules.
[Server.Redirect]
;# This section is for setting resource redirects.
;# Redirects cause custom resources to handle a client request, rather than the
;# resource identified in the request URL.
;# A redirect may apply to all endpoints in a resource, or to a particular endpoint.
;# The destination resource must have an endpoint that handles the HTTP method (e.g.; GET, POST, PUT, DELETE) and URL segments of the
;# client request. Endpoint names are not used to resolve the destination endpoint.
;# Examples:
;#
;# Redirect all endpoints of the built-in resource "Users" to the custom resource "MyUsers"
;Users={"destination":"MyUsers"}
;#
;# Redirect specific endpoints to the custom resource "MyUsers"
;Users.LoginUser={"destination":"MyUsers"}
;Users.SignupUser={"destination":"MyUsers"}
Configuring a Proxy [Server.EdgeHTTP]
The Server.EdgeHTTP section allows you to configure a proxy to be used with edge module requests. The settings include ProxyHost, ProxyPort, ProxyUserName, and ProxyPassword and the setting names are self-explanatory.
[Server.EdgeHTTP] ;# Configure proxy for edge module requests ;ProxyHost=localhost ;ProxyPort=8888 ;ProxyUserName= ;ProxyPassword=
Enabling Multi-tenancy [Server.Tenants]
The Server.Tenants section allows you to enable or disable the multi-tenant functionality of RAD Server. The Multi-Tenant functionality allows you to segment your data by tenant instead of storing all of the data together. An organization with multiple stores could use multi-tenant mode to keep data for each store seperate. DefaultTenantId is a setting that is used when in single tenant mode. It will automatically use the defined value as the tenant ID because no tenant ID exists in single tenant mode. TenantIDCookieName is the name of the cookie used to store the TenantId in EMS Console. All of the settings in this section are disabled by default.
[Server.Tenants] ;# This section defines settings for Single or Multi-Tenant modes. ;# ;# The MultiTenantMode option is used to turn on the Multi-Tenant mode. ;# If the Multi-Tenant mode is turned on, then TenantId and TenantSecret is required to access EMS Server. ;MultiTenantMode=1 ;# ;# Default Tenant is used only in the Single Tenant mode. ;DefaultTenantId=00000000-0000-0000-0000-000000000001 ;# ;# Define custom cookie name to store TenantId in EMS Console. ;TenantIDCookieName=TenantID
Configuring The Server Root Path [Server.Roots]
The Server.Roots section of the config file contains one setting called Resources. The Resources setting specifies the base URL path for all endpoints exposed through RAD Server including built-in endpoints and custom resource module endpoints. It is disabled by default. If you were to enable it and have it set to API your endpoint paths would look like this /api/version instead of /version.
[Server.Roots] ;# This section is for specifying root paths ;# ;# Specifies the root path for resources ;Resources=API
Configuring Public Paths [Server.PublicPaths]
The Server.PublicPaths section allows you to define directories from with static files can be served through RAD Server. It is a list of name values where the name is a name like Path1 and the value is a JSON string. The name is simply for your reference and can be set to the string of your choice. The JSON string consists of a virtual path definition mapping to a real directory. You can define a default file (like index.html) when browsing directly to the virtual path. Additionally, you can optionally define mime types, file extensions, and character sets of the static files that can be served through the virtual paths. If one of the entries in this section has the same path as an existing resource in RAD Server the entry here in Server.PublicPaths will override the internal resource configuration.
[Server.PublicPaths]
;# Identify directories that contain public files, such as .html
;#
;# The following entries define two different virtual directories ("images" and "content")
;# that may be used to access static files. The "directory" value indicates the physical
;# location of the static files. The optional "default" value indicates a file
;# that will be dispatched by default when browsing to the root of the virtual directory.
;# The optional "mimes" value is an array of MIME file type masks. And optional "extensions"
;# value is an array of file extensions. Only these files will be accessible from this directory.
;# The optional "charset" value specifies default charset for the files in the directory.
;Path1={"path": "images", "directory": "C:\\web\\images\\", "default": "index.html", "mimes": ["image/*"]}
;Path2={"path": "content", "directory": "C:\\web\\content\\", "default": "index.html", "extensions": ["js", "html", "css"], "charset": "utf-8"}
Configuring Dev Server Connections [Server.Connection.Dev]
EMSDevServer is the stand alone developer server and it also has a number of settings defined in the emsserver.ini file. The settings in this section only apply to the stand alone developer server and not to a production deployment on Apache or IIS. These settings cover the port it runs on, it’s SSL capabilities, cross domain settings, and its threading model. In the Server.Connection.Dev section you can configure the EMSDevServer default port and HTTPS support (enabled when set to 1). If HTTPS support is enabled you can configure the CertFile, the RootCertFile, the KeyFile, and finally the KeyFilePassword for use with an SSL connection to EMSDevServer.
[Server.Connection.Dev] Port=8080 ;# The following options enable HTTPS support. ; HTTPS=1 ;# Set HTTPS=1 to enable HTTPS, HTTPS=0 to disable. ; CertFile= ; RootCertFile= ;# When using a self-signed certificate, RootCertFile is left blank. ; KeyFile= ; KeyFilePassword=
Configuring API Cross Domain Headers [Server.APICrossDomain]
In the Server.APICrossDomain section you can set the CrossDomain setting which will control the contents of the Access-Control-Allow-Origin HTTP header in both the stand alone developer server and in a production installation. In order to allow all domains you can set CrossDomain to * (asterisk). If you are running RAD Server under Apache or IIS you may want to control the Access-Control-Allow-Origin HTTP header from within the webserver settings instead. If you set this setting and add the setting in IIS you will end up with two headers being set so only set it in one place.
[Server.APICrossDomain] ;# Write here the domains allowed to call the API. Used for Cross-Domains ;# Set CrossDomain=* to allow access to any domain. CrossDomain=
Configuring Dev Server Threads [Server.Threads.Dev]
The Server.Threads.Dev section controls a number of web server settings that the stand alone developer server, EMSDevServer, will utilize. The settings in this section only apply to the stand alone developer server. These include ThreadPool (when set to 1 it will use a thread pool scheduler), ThreadPoolSize which sets how many threads are available to handle requests, ListenQueue which controls the amount of requests which can be queued when all threads are busy, and finally KeepAlive. KeepAlive is a setting if set to 1 that will keep a connection open after an HTTP request is made so that multiple requests can be made using the same connection. Not having to make a new connection on every request can speed up requests.
[Server.Threads.Dev] ;# The following options control how EMSDevServer manages threads to handle requests ;# ;# Thread pool options ; ThreadPool=1 ;# Set ThreadPool=1 to enable thread pool scheduler, ThreadPool=0 to disable. ; ThreadPoolSize=5 ;# ThreadPoolSize indicates how many threads are available to handle requests ;# ;# Queueing options ; ListenQueue=100 ;# ListenQueue indicates how many requests can be queued when all threads are busy ;# ;# Connection options ; KeepAlive=1 ;# Set KeepAlive=1 to enable HTTP connections to keep alive, KeepAlive=0 to disable.
Finally, EMSDevConsole is also configured through the emsserver.ini file. There are a number of settings here including user information, display options, SSL capabilities, and resource paths for both EMSDevConsole and when running under Apache or IIS.
Configuring Console Logins, Cookies, And Display Options [Console]
The Console.Login section contains the login and password for your EMS Console instance (which includes EMSDevConsole and EMSConsole when installed under Apache and IIS). The Console.Cookies section includes two cookie names for User and Console (by default they are blank). Console.DisplayOptions has a ShowEdgeModules section which allows you to enable and disable EdgeModule menu items in EMS Console.
[Console.Login] UserName=consoleuser Password=consolepass [Console.Cookies] User= Console= [Console.DisplayOptions] ;# Set ShowEdgeModules=1 to enable EdgeModules menu options, ShowEdgeModules=0 to disable. ShowEdgeModules=1
Configuring Dev Console Connections [Console.Connection.Dev]
The Console.Connection.Dev settings section controls the default port of the stand alone developer server, EMSDevConsole, and it’s SSL capabilities. The settings in this section only apply to the stand alone developer server. The SSL capabilities are controlled by the HTTPS setting (when set to 1 it is enabled). While the SSL certificate can be setup using the CertFile, RootCertFile, KeyFile, and KeyPassword settings.
[Console.Connection.Dev] Port=8081 ;# The following options enable HTTPS support. ; HTTPS=1 ;# Set HTTPS=1 to enable HTTPS, HTTPS=0 to disable. ; CertFile= ; RootCertFile= ;# When using a self-signed certificate, RootCertFile is left blank. ; KeyFile= ; KeyPassword=
Configuring Console Browser Settings [Console.Browser]
The Console.Browser section allows you to define the number of rows to display in the EMS Console using the LimitRows setting and the DateFormat to display dates in under the EMS Console.
[Console.Browser] LimitRows=15 DateFormat=mm/dd/yy
Configuring Console Paths [Console.Paths.*]
The last three sections of the emsserver.ini file Console.Paths.Dev, Console.Paths.ISAPI, and Console.Paths.Apache control the path for the resource files and any web files that may be accessible. The Dev section applies to the stand-alone developer server, the ISAPI section applies to IIS, and the Apache section applies to Apache. The ResourcesFiles setting in all three sections sets the path to the webresources directory where the EMS Console JS, CSS, HTML, and image files reside. If WebFiles is blank the path set in ResourcesFiles is used instead. The Access-Control-Allow-Origin header should be set (in either emsserver.ini or from within the webserver configs) for all three deployments of EMS Console in order for the scripting elements to function correctly.
[Console.Paths.Dev] ResourcesFiles=c:\program files (x86)\embarcadero\studio\20.0\ObjRepos\EN\EMS ; WebFiles= ;# When WebFiles is left blank, DevConsole will use ResourcesFiles as WebFiles path ;# If WebFiles is used the Web Server(e.g. IIS) should include in the HTTP-Response-Header 'Access-Control-Allow-Origin' to allow cross-domain request (e.g 'Access-Control-Allow-Origin: *') [Console.Paths.ISAPI] ResourcesFiles= ; WebFiles= ;# When the webresources folder is in the same folder as the .dll, WebFiles is left blank, otherwise URL to the files ( e.g.WebFiles=http://localhost ) ;# If WebFiles is used the Web Server (e.g. IIS) should include in the HTTP-Response-Header 'Access-Control-Allow-Origin' to allow cross-domain request (e.g 'Access-Control-Allow-Origin: *') [Console.Paths.Apache] ResourcesFiles= ;WebFiles=
Summary
Read more
- The Complete Guide to RAD Server eBook by David I. (only available to RAD Server Enterprise and Architect customers)
- Mobilizing your Business with Enterprise Mobility Services Middleware by Cary Jensen
- (webinar, whitepaper, and code)
- Articles
- Introduction to Building Your First RAD Server Service by David I.
- Returning JSON: TJSONValue, TJSONWriter, and other options by David I.
- Using EMSDataSetResource Component by David I.
- How-To: Configuring Your RAD Server Instance by Eli M.
- How To: Generating Documentation for RAD Server APIs by Eli M.
- How-To: Deploy The Production Version Of RAD Server To Windows IIS by Eli M.
- How-To: Deploy The Production Version Of RAD Server To Linux by Eli M.
Check out the articles in the DocWiki