Setting up the Floating Server V2

the v2 of the floating server is currently in an open beta please submit any bugs or feedback via our support tickets as we are actively working to resolve them to move to an initial public release in a timely manner these are instructions for getting the floating server to run all core features are fully available via the api and through the built in swagger page , accessible at 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 there are a few steps you will need to take in order to run the floating server prepare the configuration file default yaml provision the server (either with certificates or with a yubikey hardware token) run the floating server and create the first admin 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 part 1 where to find the server 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 explained below) part 2 prepare the 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 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 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 setting up postgresql (local) install postgresql (if not installed) create the database and user psql postgres inside the psql prompt sql create database fsdb; create user fsuser with password 'fspassword'; grant all privileges on database fsdb to fsuser; verify the connection psql h localhost u fsuser d fsdbpsql h localhost u fsuser d fsdb you will be 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 aquire management user credentials in order to register to a license the same goes for unregisteration, 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 part 3 server provisioning 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 step 1 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 step 2 provision via ls platform open the ls platform in your browser navigate to one of your enterprise companies → go to licenses → floating servers 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 step 3 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 step 4 update configuration i n your configuration file defualt 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 start the server once your configuration file is ready, you can start the server in one of two ways option 1 executable if you are using the executable, simply run the file that matches your operating system option 2 docker pull the image 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 prepare configuration and certificates place your server configuration file in a local directory place your certificates in another directory run the container mount both the configuration and certificate directories so that the container has access 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 3 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 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