Setting up the Floating Server V2

All core features are fully available via the API and through the built-in Swagger page, accessible at:

http://<your-server-url>/swagger/index.html

Compatibility

• Environments supported: The Floating Server can be built to run on Windows and on Linux

• Client SDKs: The client applications that connect to the floating server can use one of our SDKs. This version of the floating server will initially support C++, .NET, and Java SDKs. Support for other SDKs will be added later.

• Database options: the floating server can run using SQLite or PostgreSQL.

• Provisioning options: the Floating server can be provisioned with certificate files, or with a Yubikey.

Recommended Database: Use PostgreSQL for production environments

For production environments and due to performance issues, we recommend using PostreSQL

Download the Floating Server

Steps to get the Floating Server to Run

1

Prepare configuration file

Create a configuration file called default.yaml, and place it in a subfolder called config where the binary is located: config/default.yaml

Here is a template for the default.yaml file:

default.yaml

database:
 # if using sqlite
  type: sqlite
  path: ./data/db.sqlite
# if using postgres
  type: postgres
  host: localhost
  port: 5432
  user: fsuser
  password: fspassword
  name: fsdb
  CryptoProviderKey: "" # secret used to encrypt db data in OAuth mode

server:
  port: 8080 # port on which the server runs
  Verbose: true # level of information given in logs
  DisableUserAuth: false # disable user authentication requirement, not admin!

cloud:
  UseOAuth: false
  # if authenticating with API/Shared key
  APIKey: ""
  SharedKey: ""
  # if authenticating with OAuth
  ClientId: ""
  ClientSecret: ""
  # cloud server config
  BaseURL: "" # default: "https://api.licensespring.com"
  APIPrefix: "" # default: "/api/v4/"
  ServerPublicKey: "" # default: LicenseSpring Prod's public key
  # if having Airgap licenses, fetch this key from platform
  AirgapPublicKey: ""
  # provisioning config
  UseHardwareKey: false # choose provisioning method
  PrivateKeyPath: "" # path to generated priv key. Ignore if using hardware key
  CertificatePath: "" # path to cert received from LS. Ignore if using hardware key
  CACertificatePath: "" # path to CA certificate, in both provision methods

Database Configuration

The database section defines how the application connects to the underlying database. Two database types are currently supported: SQLite and PostgreSQL.

please comment out or delete the fields from default.yaml for the database you will not be using.

SQLite

When using SQLite, make sure the database directory specified in the YAML configuration file actually exists. For example, if you're using ./data/db.sqlite as shown in the sample above, ensure that the data directory exists. The Floating Server will not create missing directories automatically. The database file can be named anything. The server will create it if it doesn't exist.

If you're using SQLite, provide the file path for the database file:

type: sqlite path: ./data/db.sqlite

PostgreSQL

To use PostgreSQL instead of SQLite, update the default.yaml with the following fields:

Fields:

• host: The PostgreSQL server address (usually localhost for local development)

• port: Port number (default is 5432)

• user: The PostgreSQL username

• password: The password for the specified user

• name: The name of the database to connect to

type: postgres host: the posgres host port: the postgres port user: the user in db password: password name: give the db a name

Setting Up PostgreSQL (Local)

• Install PostgreSQL (if not installed)

• Create the database and user:

  • Run psql postgres and inside the psql prompt execute:

SQL - Create DB and User

CREATE DATABASE fsdb;
CREATE USER fsuser WITH PASSWORD 'fspassword';
GRANT ALL PRIVILEGES ON DATABASE fsdb TO fsuser;

• Verify the connection:

bash

psql -h localhost -U fsuser -d fsdb

powershell

You will be prompted for the password that you set above, "fspassword" or whatever you originally used.

This process in MacOS is shown in the following picture.

CryptoProviderKey

CryptoProviderKey is a secret key you may use to encrypt data before storing it in the database.

If you are using OAuth instead of our API and Shared keys to authenticate, you must define CryptoProviderKey to ensure your data is securely encrypted.

If you are using API/Shared keys for Authentication, then you do not need to specify CryptoProviderKey, and the database will use the SharedKey for encryption instead.

Server Configuration

The server section defines the server’s port and log verbosity. You can keep the default values unless changes are needed, but do not remove these fields, they are required.

• Port: The network port the server listens on.

• Verbose: Controls the amount of logging detail. We recommend setting this to true in development for more detailed output, and to false in production.

• DisableUserAuth: If set to true, the floating server will not require users to acquire management user credentials in order to register to a license. The same goes for unregistration, feature register/unregister, consumption and feature consumption. We recommend using this mode only for tests. More on this on the section related to user management.

Cloud Configuration

The cloud section depends on your authentication method:

• If using API and Shared keys, fill out APIKey and SharedKey.

• If using OAuth, set UseOAuth to true and provide ClientId and ClientSecret.

• When using OAuth:

  • Update the database section with UseOAuth: true.

  • Provide a CryptoProviderKey. This key encrypts data stored in the database.

  • If not using OAuth, the SharedKey handles encryption.

If you are using a BaseURL or APIPrefix different from the default, specify them in the cloud section. In this case, you must also provide the server’s public key as shown in the sample config file above. In this format:

ServerPublicKey: |
  -----BEGIN PUBLIC KEY-----
  (your public key here)
  -----END PUBLIC KEY-----

2

Provision the server

Before starting the floating server, you must provision it. This step ensures that only legitimate instances of the server are used and prevents unauthorized replicas from running.

Generate a Key Pair

First, create a private–public key pair locally. This will be used to generate a Certificate Signing Request (CSR):

openssl genrsa -out private.key 2048

Provision via LS Platform

1. Open the LS Platform in your browser.

2. Navigate to one of your Enterprise Companies → go to Licenses → Floating Servers.

3. Click the Provision the Floating Server button.

• Choose Certificate as the authentication type.

• Enter a name for your floating server and optionally set an expiration date for the certificate.

• Follow the on-screen instructions to generate a CSR (Certificate Signing Request) locally.

• Copy the contents of the generated request.csr file and paste it into the form.

• Click Confirm.

Download and Save Certificates

• Download the issued certificate and save it locally (e.g., certificate.crt).

• Also download the CA chain certificate (e.g., chain.crt).

• Make sure your previously generated private key is also accessible.

Update Configuration

In your configuration file default.yaml, under the cloud section, provide the paths to your key and certificate files:

cloud:
  UseHardwareKey: false # choose provisioning method
  PrivateKeyPath: "" # ignore if using hardware key
  CertificatePath: "" # ignore if using hardware key
  CACertificatePath: "" # path to CA certificate, in both provision methods

3

Run the Floating Server

Prior to running the floating server for the first time, please ensure the configuration file is setup correctly, and that the data folder exists and is located at the path specified in the configuration file.

There are currently two options for running the server:

• Executable (recommended if you don’t want Docker)

  • Download the executable file that matches your operating system from here.

    • floating-server-linux-amd-2.0.0-beta.1.zip

    • floating-server-windows-amd-2.0.0-beta.1.zip

  • Run the executable directly.

  A Docker Image is currently being prepared and will be made available soon.

• Docker

  • Pull the image from Docker Hub.

  • Run the container from the pulled image.

  • The configuration file and provisioning steps are the same for both methods. The only difference is that in the Docker case, you must mount the configuration and provisioning files so that the container can access them (details below).

Start the Server — Executable

Run the executable that matches your OS:

./floating-server

Start the Server — Docker

1. Pull the image:

docker pull licensespring/floating-server-v2:v2.0.0-beta.1

1. Set up PostgreSQL

   • Start a PostgreSQL instance (local or containerized).

   • Note down the host, port, username, password, and database name.

   • Update the configuration file with these PostgreSQL connection details.

2. Prepare configuration and certificates

   • Place your server configuration file in a local directory.

   • Place your certificates in another directory.

3. Run the container — mount both config and cert directories:

docker run -d --name fsv2 --network fsnet -v /path/to/config:/app/config -v /path/to/certs:/app/certs -p 8080:8080 licensespring/floating-server-v2:v2.0.0-beta.1

• Replace /path/to/config with the directory containing your config file.

• Replace /path/to/certs with the directory containing your certificates.

• Adjust the -p mapping if you want to expose the server on a different port.

Option: docker-compose

A docker-compose.yml file is shipped with the documentation. Running this file will automatically set up both a PostgreSQL container and the Floating Server container together. This is the quickest way to get everything running with a single command.

First-time Admin Setup

When the Floating Server starts for the first time, there are no users or admins configured. The first required step is to set a password for the initial admin account. Once set, you can log in using the username admin and the chosen password. After logging in as the admin, you will have the ability to add additional users.

This initial password setup can be done either through the UI or by calling the API endpoint:

POST /api/v5/auth/initial-password

If you are using the UI and navigate to the Floating Server’s URL before setting up an admin account, you will automatically be redirected to the setup page for creating the initial admin password. This page is shown in the image below.

When running the Floating server for the first time, the initial Username that you are setting the password for is admin

Once logged in, you should see the admin panel to the floating server: