Skip to main content

Quickstart with the Xillio Link Redirector

This page will guide you through the quickest way to get started with the Xillio Link Redirector. In this guide we will get you started with your first database connection, some basic configurations, creating your first rules, and testing to see if everything works.

Before we begin​

Before proceeding, make sure you have a license for the Xillio Link Redirector. This should have been given to you as part of your onboarding.

Next, make sure you have at least the latest version of docker and docker-compose installed. At the time of writing this documentation the recommended version should be equal to, or higher that the following.

$ docker --version
Docker version 20.10.13, build a224086
$ docker-compose --version
Docker Compose version v2.3.3

Step 1. Setup project folder​

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

Throughout this quickstart we will add files to this folder and in the end it should look something like:

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

Step 2. Create your configuration file​

Download our sample configuration file at /examples/quick-start/config.yml.

This should look something like the following:

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/localhost.key            # The path towards your certificate key file
  certificateFile: ./certs/localhost.cert   # The path towards your certificate file
  # caFile: ./certs/rootCA.cert             # (Optional) Override the root CA to use
  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
  # caFile: ./certs/rootCA.cert             # (Optional) Override the root CA to use
  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)

Step 3. Copy your license​

Next, open your configuration file, and add your license key to the license.key-directive. If you've used the example from above, you need to substitute the YOUR-KEY-HERE text with your key.

Step 4. Create testing certificates​

For this step you can either create a new self-signed certificate or use one you already own. In case of the latter, put the certificate and key-file in the /xlr/certs folder. Be sure to validate that the file names match with the files in your configuration from step 2.

Creating self-signed certificates​

In order to create a self-signed certificate we can use the OpenSSL tool. Execute the following commands:

$ mkdir -p certs
$ openssl req -newkey rsa:2048 -nodes -keyout certs/localhost.key -x509 -days 365 -out certs/localhost.cert

When executing the second argument, you will be promted with some additional information. This will generate two files: your private key file (.key) and public certificate file (.cert).

Self-signed certificates

Self-signed certificates are not recommended for production environments! We only use them here for testing purposes.

Step 5. Setup third-party services​

Download our sample docker-compose file at /examples/quick-start/docker-compose.yml.

This file contains all the additional services we will use for this quickstart. In this quickstart we will use Postgres as a database and Adminer as a tool that we can use for debugging it. Additionally, we will use InfluxDB as a time-series database to store runtime metrics of the system.

docker-compose.yml
version: '3.7'

services:

  db:
    image: postgres:14.2
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: example
      POSTGRES_DB: xlr
    volumes:
      - ./.docker/db/data:/var/lib/postgresql/data 
    ports: 
      - 5432:5432
    
  metrics:
    image: influxdb:2.1-alpine
    restart: always
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=influx
      - DOCKER_INFLUXDB_INIT_PASSWORD=development
      - DOCKER_INFLUXDB_INIT_ORG=xillio
      - DOCKER_INFLUXDB_INIT_BUCKET=xlr
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=development
    volumes: 
      - ./.docker/metrics/data:/var/lib/influxdb2
    ports:
      - 8086:8086

  xlr: 
    image: xillio/link-redirector:latest
    restart: always
    ports:
      - 80:80
      - 443:443
      - 8080:8080
      - 8443:8443
    volumes: 
      - ./certs:/app/certs
      - ./config.yml:/app/config.yml

Step 6. (Optional) Create database schemas​

While this step is optional, it is highly recommended if you are using a database other than MongoDB, as is the case in this quickstart guide. For SQL databases, creating the database schema is a prerequisite before use. Let's proceed with setting up the schema. We will give a brief overview of how to do this for different environments, for more information please refer to the Database Schema Initiation guide.

To begin, update the docker-compose.yml file from Step 5 by adding an environment variable to the xlr-service. Here's how your file should look, with the new addition highlighted:

docker-compose.yml
# ...
xlr:
    image: xillio/link-redirector:latest
    restart: always
    environment:
        XLR_DANGEROUS_SYNCHRONIZE: true
    ports:
        - 80:80
        - 443:443
        - 8080:8080
        - 8443:8443
    volumes:
        - ./certs:/app/certs
        - ./config.yml:/app/config.yml
# ...

Setting the XLR_DANGEROUS_SYNCHRONIZE variable to true enables the synchronization of the database schema. After making this change, restart the xlr-service with the following command:

docker-compose restart xlr

Restarting the xlr-service will synchronize the database schema. Once the application has successfully started, it is advisable to remove the XLR_DANGEROUS_SYNCHRONIZE variable from the docker-compose.yml-file to prevent any unintended changes.

danger

Keeping the XLR_DANGEROUS_SYNCHRONIZE variable set to true allows the application to overwrite the database schema on every restart. This poses a risk of data loss and is not recommended for production environments.

Step 7. Verify setup​

Verify that the Xillio Link Redirector is working by opening your browser and visit the following URLs:

This window should show the current version and the system time of the server it is running on.

Note: You can validate that the additional services are running in a similar fashion. Influx is available through http://localhost:8086

Next steps​

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