XtremeDocumentStudio
.NET
PDFOne
.NET
XtremeDocumentStudio
(for Java)
PDFOne
(for Java)
XtremeDocumentStudio
Delphi
eDocEngine
VCL
PDFtoolkit
VCL
StarDocs
Web APIs

Configuring the StarDocs On-Premises API server

Using the StarDocs On-Premises Administration Console, setting up secure end-points and more
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.

Note: The article will be updated as more settings are exposed via the administration console.

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. You can login with the credentials supplied at the time of purchase of your license.

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

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.

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.

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.

---o0O0o---

Our .NET Developer Tools
XtremeDocumentStudio .NET

Multi-format document-processing component suite for .NET developers.

PDFOne .NET

A .NET PDF component suite to create, edit, view, print, reorganize, encrypt, annotate, and bookmark PDF documents in .NET applications.

Our Delphi/C++Builder developer tools
XtremeDocumentStudio Delphi

Multi-format document-processing component suite for Delphi/C++Builder developers, covering both VCL and FireMonkey platforms.

eDocEngine VCL

A Delphi/C++Builder component suite for creating documents in over 20 formats and also export reports from popular Delphi reporting tools.

PDFtoolkit VCL

A Delphi/C++Builder component suite to edit, enhance, view, print, merge, split, encrypt, annotate, and bookmark PDF documents.

Our Java developer tools
XtremeDocumentStudio (for Java)

Multi-format document-processing component suite for Java developers.

PDFOne (for Java)

A Java PDF component suite to create, edit, view, print, reorganize, encrypt, annotate, bookmark PDF documents in Java applications.

Our Platform-Agnostic Cloud and On-Premises APIs
StarDocs

Cloud-hosted and On-Premises REST-based document-processing and document-viewing APIs

Privacy | Legal | Feedback | Newsletter | Blog | Resellers © 2002-2017 Gnostice Information Technologies Private Limited. All rights reserved.