Before you can use Data Connectors you must have a running instance of the Data Link Server. The Data Link Server is a Java web application, hosted on an embedded Apache Tomcat HTTP server that relays and translates any requests made to your Telerik Platform app to your relational database.
This article explains the installation of a Data Link Server on a Linux machine. In order to install it on a machine running Microsoft Windows, follow the instructions in Setting Up Data Link Server on Windows.
This article is organized as follows:
- Acquiring the Installation Package
- Running the Data Link Server
- Testing the Server
- Setting Up Authentication
- Enabling SSL
- Updating the Data Link Server
- Uninstalling the Service
Before starting the Data Link Server installation make sure you have the following:
- A machine running Linux that has network connectivity to the database server. This machine will host the Data Link Server.
- Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) version 8 or later installed.
- An environment variable named
JAVA_HOMEset to the path where the JDK (or the JRE) is installed. Detailed instructions can be found in the Oracle documentation
- The Upstart daemon for running the server as a system service.
Follow these steps to download and extract the Data Link Server ZIP package.
- Navigate to the Downloads page.
- Under Select platform or tool, select Data Link Server.
- Click the Download button and save the ZIP file to your hard drive.
- Extract the files to a suitable location, for example,
user@linux:~$ unzip TelerikDataLinkServer.zip -d /opt/telerikdatalink
You can run the server application once or install it as a system service for continuous running.
When the server is starting it reads the
application.propertiesconfiguration file. Always check if it is set up correctly otherwise the server uses default values. You can learn how and when to set some of the more important options in the remaining sections of this article. Keep in mind that configuration updates take effect after restarting the Data Link Server.
The Data Link Server comes with a shell script that can be used to run the server without installing it.
To run the Data Link Server once, open a terminal and go to the bin directory inside the folder where you extracted the Data Link Server server zip package, then run the following command:
Running the server from the command line is not the best solution if you need it always running. A better alternative is to install it as a service, so it is started automatically when the machine boots. The Data Link Server comes with an installation script that generates an Upstart configuration and starts the service.
To install the service, open a terminal window and go to the bin directory inside the folder where you extracted the Data Link Server package, then run the command below as root. The only required parameter (
datalinkuser in the example) is the name of a local user account that will be used to run the service.
For the following instructions, you need to be executing the commands as the root user.
root@linux:~/TelerikDataLinkServer/bin$ bash installLinuxService.sh datalinkuser
To restart the service (for example after modifying the
application.properties configuration options), use the following command:
root@linux:~/TelerikDataLinkServer/bin$ service datalink restart
The easiest way to check if the Data Link Server server is running is to access its URL (http://machine-name.domain:port) with the
curl command. For example, if you are testing from the machine where the server is installed and it runs on the default port, the URL would be
http://localhost:9090. The expected response is HTTP status code 200 and a simple JSON-formatted message:
user@linux:~/TelerikDataLinkServer/bin$ curl localhost:9090
The security is not complete without configuring the server-to-server authentication between Telerik Platform and your instance of the Data Link Server. The integrated authentication mechanism restricts the access to your Data Link Server, allowing in only a Telerik Platform app authenticated with an appointed key known to both parties. The secret key is automatically generated for each Telerik Platform app.
Take these steps to set up authentication:
Download the key from the Create a Data Connector/Edit page. You can access the page in your Telerik Platform app on Data > Data Connectors > Create a Data Connector/Edit > Download Authentication Key.
Alternatively, you can use the RESTful API to download the authentication key.
The file name of your download will be the Telerik Platform App ID followed by the .txt file extension (for example
3YVPn8Al5Vi8Yfe4.txt). The content of the file is a JSON Web Token, the secret key used by Telerik Platform and the Data Link Server to sign and validate requests.
Copy the downloaded file to the
keyssubfolder of the Data Link Server installation folder.
- Open the
application.propertiesconfiguration file and ensure that the
security.token.enabledis uncommented and set to
If for some reason you believe that your secret key is compromised, you can regenerate it as discussed in Managing the Authentication Key Using the RESTful API.
By default, the Data Link Server works over HTTP. It is strongly recommended that you configure an SSL certificate so that Telerik Platform can communicate with the Data Link Server over HTTPS.
Take these steps to enable SSL:
Acquire an SSL certificate.
The supported format is the Java KeyStore (JKS) format, the standard Java format. You can generate a JKS using the
keytoolcommand-line utility. The same tool is also used for importing existing certificates into the keystore. For complete instructions see the official Apache Tomcat documentation.
After you have acquired the keystore file containing the certificates, configure the
Use the information in this paragraph only when you have a running Data Link Server and want to update it with the latest version of the package. In the steps below you will learn how to install the new application package while preserving the already applied configuration.
- Follow the steps for Uninstalling the Service (in case you are running the server as a system service) or stop the running instance of the Data Link Server from the console window.
- Backup the following files from the current installation folder of the Data Link Server.
data-connectors.config—stores the database tables to content types mappings
application.propertiesfile (if available)—stores the Data Link Server configuration
- Java KeyStore (JKS) file (
.keystore) (if available)—stores the SSL encryption key/certificate
keys/<security-key-file.txt>(if available)—stores the server-to-server authentication token
Remove or rename the current directory to something else—for example "TelerikDataLinkServer.old".
user@linux:~/$ mv TelerikDataLinkServer TelerikDataLinkServer.old
- Acquire and extract the installation package as explained in Acquiring the Installation Package.
data-connectors.configfile in the ".old" directory and copy it to the new one:
user@linux:~/$ cp TelerikDataLinkServer.old/data-connectors.config TelerikDataLinkServer
- Examine and configure (if needed) the
- Optionally, restore your Java KeyStore (JKS) file (
keys/<security-key-file.txt>file from the backup directory to their respective locations in the new Data Link Server folder.
- Follow the steps for Running as a Service or Running from the Command Prompt respectively.
You can run an uninstallation script to remove the service. It is located in the same
bin folder as the installation script. It does not require any parameters.
To uninstall the service, run this command as root:
root@linux:~/TelerikDataLinkServer/bin$ bash uninstallLinuxService.sh
You are now ready to create your Data Connector in Telerik Platform. You can learn how in Creating an SQL Data Connector Using the Portal and Managing Content Types Using the Administration API.