From db107eff288ca1282b6d5d71045f9ab88a8040c8 Mon Sep 17 00:00:00 2001 From: Arthur Desplanches Date: Fri, 1 Mar 2024 11:42:35 +0100 Subject: [PATCH 1/3] Improve documentation and quickstart setups --- README.md | 75 +++++++++++++++++++++++++++++----------------- docker-compose.yml | 4 +-- 2 files changed, 49 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index cef4380..17e1e64 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,11 @@ Export license usage for SideFX license server to Prometheus. ## Requirements +This project is expected to run in a docker container, so one of the +requirements is a docker engine. + +### Binaries + To run this exporter, you need to provide the binaries `hserver` and `sesictrl`. They are part of the houdini install on Linux, and you can retrieve them from their respective destination paths after installing houdini : @@ -15,21 +20,54 @@ The version of houdini (which translates 1:1 with the version of these binaries) should be above the version of your license server. At the time of writing, the exporter has been tested with versions 19.5 and 20. +The available docker compose configuration expects these binaries to be +installed in the `./hfs-bin/` directory, but you can change that as you see fit. + +### Configuration + +You will need to provide a configuration file to the exporter. + +The easiest way to get started is to copy the template included in the +`examples` directory to the root of this repo, and modify the +`license_server_hostname` to your sidefx license server hostname : + +```bash +cp ./examples/config.yml . +sed -i 's/sidefx-licserv.example.com//' config.yml +``` + ## Usage -### Quick start from source +### Quick start -Here is a quick way to test the application from source, it requires a docker -engine with the docker compose plugin, and gnu make : +After completing the requirements, you can simply start the exporter with the +provided docker compose configuration : -- Retrieve the `hserver` and `sesictrl` binaries from a Houdini install on - Linux, and store them both in a directory named `./hfs-bin`. -- Copy the `./example/config.yml` file to the root of the repository and adjust - the `license_server_hostname` entry to match your license server. -- Start a dev build with the command `make run`. -- The exporter should be running on your host, on the port `9102`. +```bash +docker compose up +``` -### Command line parameters +Or if you prefer to use vanilla docker : + +```bash +docker run \ + -p "9102:9102" \ + -v "./config.yml:/etc/sidefx-lic-exporter/config.yml" \ + -v "./hfs-bin/hserver:/usr/local/bin/hserver" \ + -v "./hfs-bin/sesictrl:/usr/local/bin/sesictrl" \ + ghcr.io/forticheprod/sidefx-lic-exporter:latest +``` + +The exporter will be available on port `9102`. + +### Quick start from source + +If you want to run the application from source (e.g. to test changes) : + +- Follow the requirements, and make sure you have gnu make installed +- Start the dev environment in docker with the command `make dev` +- Inside the container, start the exporter with the command + `sidefx-lic-exporter` and any flags you want ``` usage: sidefx-lic-exporter [-h] [--config CONFIG] [-l LOG_LEVEL] [-p PORT] @@ -44,20 +82,3 @@ options: -p PORT, --port PORT port to run the exporter on Default : 9102 ``` - -### Configuration file - -A YAML configuration file is expected, with the following parameters : - -```yaml ---- -# The interval at which the license data will be scrapped from the license -# server -scrape_interval: 15 -# The path to the two required binaries -hserver_path: "/usr/local/bin/hserver" -sesictrl_path: "/usr/local/bin/sesictrl" -# The hostname, or IP address of your sidefx license server you want to scrape -# license data from -license_server_hostname: "sidefx-licserv.example.com" -``` diff --git a/docker-compose.yml b/docker-compose.yml index dfec188..48c9896 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,9 +1,7 @@ version: "3" services: exporter: - build: - context: . - dockerfile: ./Dockerfile + image: ghcr.io/forticheprod/sidefx-lic-exporter:latest command: - --config=/etc/sidefx-lic-exporter/config.yml restart: unless-stopped From 917b46060791634266d94b629c85a4945a5ee0d8 Mon Sep 17 00:00:00 2001 From: Arthur Desplanches Date: Fri, 1 Mar 2024 12:18:15 +0100 Subject: [PATCH 2/3] Simplify language --- README.md | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 17e1e64..36c6408 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,31 @@ Export license usage for SideFX license server to Prometheus. ## Requirements -This project is expected to run in a docker container, so one of the -requirements is a docker engine. +This project is expected to run in a Docker container, so you'll need a Docker +engine. ### Binaries -To run this exporter, you need to provide the binaries `hserver` and `sesictrl`. -They are part of the houdini install on Linux, and you can retrieve them from -their respective destination paths after installing houdini : +To run this exporter, you need the `hserver` and `sesictrl` binaries. +They are part of the houdini install on Linux, and can be found here : - `/opt/hfs/bin/hserver` - `/opt/hfs/houdini/sbin/sesictrl` -The version of houdini (which translates 1:1 with the version of these binaries) -should be above the version of your license server. At the time of writing, the -exporter has been tested with versions 19.5 and 20. +Make sure your Houdini version matches or is newer than your license server +version. Currently, this exporter has been tested with versions 19.5 and 20. -The available docker compose configuration expects these binaries to be -installed in the `./hfs-bin/` directory, but you can change that as you see fit. +The available Docker compose configuration expects these binaries to be +installed in the `./hfs-bin/` directory, but you can use the directory of your +choice. ### Configuration You will need to provide a configuration file to the exporter. -The easiest way to get started is to copy the template included in the -`examples` directory to the root of this repo, and modify the -`license_server_hostname` to your sidefx license server hostname : +To get started, copy the template from the `examples` directory to the root of +this repository, and modify the `license_server_hostname` to match your SideFX +license server: ```bash cp ./examples/config.yml . @@ -40,14 +39,13 @@ sed -i 's/sidefx-licserv.example.com//' config.yml ### Quick start -After completing the requirements, you can simply start the exporter with the -provided docker compose configuration : +Once you've met the requirements, start the exporter using Docker compose : ```bash docker compose up ``` -Or if you prefer to use vanilla docker : +Or, if you prefer vanilla Docker : ```bash docker run \ @@ -64,10 +62,10 @@ The exporter will be available on port `9102`. If you want to run the application from source (e.g. to test changes) : -- Follow the requirements, and make sure you have gnu make installed -- Start the dev environment in docker with the command `make dev` -- Inside the container, start the exporter with the command - `sidefx-lic-exporter` and any flags you want +- Ensure you have the requirements installed and GNU make +- Start the development environment in Docker with `make dev` +- Inside the container, start the exporter with + `sidefx-lic-exporter` and any desired flags ``` usage: sidefx-lic-exporter [-h] [--config CONFIG] [-l LOG_LEVEL] [-p PORT] From 84eb03585b2024115a7317b75ee30ba4e8fc04ee Mon Sep 17 00:00:00 2001 From: Arthur Desplanches Date: Fri, 15 Mar 2024 11:46:05 +0100 Subject: [PATCH 3/3] Explain binaries path config more thoroughly --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 36c6408..5480cbf 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,14 @@ Make sure your Houdini version matches or is newer than your license server version. Currently, this exporter has been tested with versions 19.5 and 20. The available Docker compose configuration expects these binaries to be -installed in the `./hfs-bin/` directory, but you can use the directory of your -choice. +installed in the `./hfs-bin/` directory. Use this one for a quick-start. + +If you wish to change this path, it's something you can do in +`docker-compose.yml` in the volumes section or an ad-hoc Docker command with the +-v flag (see below for examples). Docker will map the path to the binaries +inside the docker container (in `/usr/local/bin` by default), and then the +exporter will use the `hserver_path` and the `sesictrl_path` keys in the +`config.yml` to get their location. ### Configuration