Home » Newsletter » August 2016

by Santosh Patil

If you are new to StarDocs, we suggest you read the introductory article first.

The Gnostice StarDocs On-Premises API server provides a web-based administration console for configuring the server. This article explains the various settings available and how to configure them.

The URL where the administration console is available is displayed in the virtual appliance window. See below for a sample screenshot.

Open a web-browser on a machine on the same network and navigate to the administration console URL. The default username and password are "admin" and "stardocs!@#" without quotes. You are advised to change this password after you login the first time.

The below screenshot shows the administration console home page.

Here is the list of tasks that can be performed in the administration console.

• Provision and manage trial or paid server license
• Manage API keys
• Configure SSL certificate for secure access
• Update StarDocs server software
• Collect server debug logs

Provision and manage trial or paid server license

Navigate to the license management tab by clicking on Server Licensing on the left-menu. The tab shows the currently activated license along with options to manage it.

Note that all licensing related operations require the server to have public internet access since the Gnostice License Server needs to be reachable. You can turn off public internet access once you complete performing license related operations.

• Activate a new license

  Follows the steps below for activating a new license:
  1. Enter your new trial or paid license key obtained from Gnostice
  2. Enter your email address and click the Activate button
  3. After successful activation you must create a new App to get the API credentials for use in your application
  
  Note that there can only be one license activated at any given time, hence any existing activation (along with its data) will be lost if a new license is activated.

• Revoke an activated license

  The activation is tied to the machine on which the license is activated. Therefore before making any hardware changes or before moving the license to a new machine you must first revoke the activation. To revoke an activated license, simply click on the Revoke Activation button on the Server Licensing page. You can reinstate the activation after making the hardware changes. If you are moving the license to another installation then you can simply transfer the license by activating it on the newer installation after it has been revoked from the older one.

• Reinstate a revoked activation

  After making the necessary hardware changes you can reinstate the activation to resume document operations on the server. To reinstate the activation, simply click on the Reinstate Activation button on the Server Licensing page.

Manage API keys

To make API calls on StarDocs, you need an API Key to authenticate the calling app with the StarDocs server. To create an API key navigate to the apps tab by clicking on Apps Management on the left-menu. This tab shows the currently configured apps along with options to manage them, and create new ones.

• Create a new App

  You can create a new set of API keys by adding a new application. Click the Add button and follow the prompts that appear. Upon successful app creation a new set of API key and secret will be generated. Use this key and secret in your application to authenticate to the StarDocs server.

• Edit App

  You can regenerate a new API secret or modify the settings for an App by clicking the Edit button. Note that the Edit button also reveals the currently set API secret.

• Delete App

  If you suspect that your API keys have been compromised, you can delete the App and create a new one. Needless to say, all occurrences of the old API Key and Secret in your source code needs to be updated with the new ones.

Configure SSL certificate for secure access

Note: The following instructions use the popular OpenSSL utility. This page lists some binary distributions of OpenSSL for operating systems like Windows.

If you wish to encrypt the traffic between your application and the StarDocs API server then you should use the secure end-point URL of the server (https://<stardocs_ip_or_domain>:8443/stardocs/v1). It is recommended that you do this if your application is communicating with the StarDocs server over an unsecured network.

In order to use the secure end-point URL of StarDocs you will need to provide an SSL certificate and its corresponding key. The SSL certificate needs to be obtained from a trusted Certifying Authority (CA) by sending a Certificate Signing Request (CSR). Note that self-signed certificates will NOT work.

Here are the steps to prepare a Certificate Signing Request using OpenSSL utility.

1. Create a private key of sufficient strength

   openssl genrsa -out server_key.pem 2048
   

2. Generate a CSR (Certificate Signing Request). Ensure to mention the StarDocs server's fully qualified domain name in the Subject Common Name (CN) field. You can also obtain a wildcard SSL certificate to cover your main domain (say your application end-point) and put StarDocs server on a sub-domain so that the same certificate covers both. Another option is to obtain a certificate that covers multiple domains by using the Subject Alternate Names (SAN) field.

   openssl req -new -key server_key.pem -out server.csr
   

3. You need to submit the CSR file (

   server.csr

   ) to your CA for signing. In response, the CA will issue you the public-key certificate.
4. Combine the public key certificate, intermediate certificates (if any) and private key into a PKCS#12 (PFX) file and protect it by a passphrase. Ensure to remember this passphrase since it needs to be provided in the administration console.

   openssl pkcs12 -export -out stardocs.pfx -inkey server_key.pem 
       -in server_cert.pem -certfile intermediate.crt
   

   where

   server_cert.pem

   is the certificate issued by the CA and

   intermediate.crt

   is the CA's intermediate certificate or certificate chain leading up to the CA's root certificate.

Setup the SSL certificate in the administration console

Navigate to the SSL settings by clicking on Network on the left-menu. The SSL tab shows you details of the currently configured SSL certificate and allows you to upload a new one. See the screenshot below.

Upload the PKCS #12 (PFX) certificate-key pair file stardocs.pfx we created above and specify the passphrase we used to protect it. Once the file is uploaded, if all goes well, the tab will show the details of the new certificate. An appropriate message will be shown on errors.

After successfully configuring the SSL certificate you can start using the secure end-point of the StarDocs server. To check if the configuration is fine, please visit the home page https://<stardocs_ip_or_domain>:8443/ and ensure that the browser isn't blocking the page.

Update StarDocs server software

Gnostice may sometimes release minor updates and bug fixes as a small update package rather than a full server build for easier deployment. To apply such updates you can download the package and navigate to System -> Update. The tab shows the current server software version and allows the update package to be uploaded for deployment. Once an update is successfully applied the displayed version number is updated.

NOTE: Please be aware that software update will cause ongoing API requests to be dropped. So ensure that the server is not being used before attempting to perform the update.

The below screenshot shows the update tab.

Collect server debug logs

In the unlikely event of the server running into any issues we may ask for the server debug logs to investigate the issue. You can navigate to System -> Logs to download the logs and send it to us.

The below screenshot shows the logs tab.