Skip to main content

Start a local instance

With this guide we will help to setup the Xillio Link Redirector on your local system. Most of these steps should apply to Windows, Mac, and Linux devices. If there is a special action that should be performed on a specific OS, it will be explained in the steps below.

info

These steps should work on almost any environment whether this is a baremetal-instance or a VM in a cloud environment.

Before you begin​

Before proceeding, make sure you have access to a supported database. The easiest way to get started is through installing Postgres Locally.

Step 1. Setup your project directory​

To keep things organized, create a new folder to store all your files. For this guide we will assume this folder is called xlr.

This is the suggested folder structure throughout this guide.

xlr/
 ├── certs/
 │   ├── localhost.crt
 │   └── localhost.key
 ├── config.yml
 └── docker-compose.yml

Download the latest version of the Link Redirector from our download portals. The download should be a zip-file that contains the binaries, configuration files, and other necessary files. You can extract the contents of the zip-file to the folder you created in the previous step. Note that this folder now contains a bin-folder containing the exectuables.

Step 3. Create your configuration file​

If you downloaded the application from our download portal, the zip-file that was downloaded contains a default-config.yml. This contains all the configuration options that are available for the application. You can copy this file and rename it to config.yml in the root of your project folder. This will give you a good starting point for your configuration. In this file we will add all our configuration options to make sure our application is working just how we want.

Alternatively you can copy and paste the following content into your configuration file:

config.yml
# Information on how the Xillio Link Redirector should act and be exposed towards the outside world
license:
  key: YOUR-KEY-HERE

logger:
  type: simple            # The type of logger to use. choose from `simple`, `json`, or `void` (default: simple)
  showStackTrace: false   # Print the stack trace to stdout (default: false)
  levels:                 # List of log-levels that should be shown. (default: all levels)
    - audit               # Possible values are ['trace', 'audit', 'http', 'debug', 'info', 'warn', 'error']
    - http
    - info
    - warn
    - error

proxy:
  port: 80                  # The port to use for HTTP connections (default: 80)
  requestLogging: true      # Enable logging incoming request to the console (default: false)
  requestMonitoring: true   # Enable measuring request data to a metric service (default: false)

  # (Optional) Options for SSL connections.
  # If `httpsPort` is defined, the `keyFile` and `certificateFile` also need to be specified.
  # httpsPort: 443                       # The port to use for HTTPS connections (default: 443)
  # keyFile: ./certs/demo.key            # The path towards your certificate key file
  # certificateFile: ./certs/demo.cert   # The path towards your certificate file
  # forceHttps: true                     # Redirect all incoming HTTP request towards the HTTPS ports (default: false)

  # (Optional) Additional configuration
  # timeout: 10000                  # Timeout for proxied request in milli seconds (default: 10000)
  # addForwardedForHeaders: false   # Add all headers of the incoming request to the proxied request (default: false)
  # acceptUntrustedProxyTLS: false  # Allow self-signed certificates for proxied requests (default: false)
  # logProxyRequests: false         # Log the proxied requests (default: false)
  # maxUrlLength: 256                         # The maximum length of the URL (default: 256)

api:
  port: 8080                # The port to use for HTTP connections (default: 8080)
  requestLogging: true      # Enable logging of incoming request to stdout (default: false)
  requestMonitoring: true   # Enable measuring of request data to a metric service (default: false)

  # (Optional) Options for SSL connections.
  # If `httpsPort` is defined, the `keyFile` and `certificateFile` also need to be specified.
  # httpsPort: 8443                           # The port to use for HTTPS connections (default: 8443)
  # keyFile: ./certs/localhost.key            # The path to your certificate key file
  # certificateFile: ./certs/localhost.cert   # The path to your certificate file
  # forceHttps: true                          # Redirect all incoming HTTP request towards the HTTPS ports (default: false)

  # basePath: /xlr/api                        # The base path for all api endpoints (default: /xlr/api)
  # maxUrlLength: 256                         # The maximum length of the URL (default: 256)

# Configuration on the database connection
database:
  type: postgres
  url: postgresql://postgres:example@db:5432/xlr

# (Optional) Configuration for the metrics service to use for request and performance metrics
metrics:
  type: influx
  url: http://:development@metrics:8086
  organization: xillio
  performanceMonitoring: true  # Enable measuring system performance to a metric service (default: false)
caution

At this point you can copy the file as is and only need to change your database configuration. For local testing you can leave the SSL-configuration disabled so you do not need to worry about certificates just yet.

Step 4. Collect your License key​

As part of your onboarding package you have received a license key that looks like XXXXX-XXXXX-XXXXX-XXXXX. Copy your key and replace YOUR-KEY-HERE in your configuration file. This line has been highlighted in the example configuration in the previous step.

Step 5. Setup your database​

Before you can start the application you need to setup your database. Please refer to the database setup guide for more information.

Step 6. Run the application​

To start the application you can run the following command in the root of your project folder:

.\bin\link-redirector-windows.exe

Whats next?​

After these steps you should have your instance of the Xillio Link Redirector up and running. Next up are the following guides: