Merge pull request #145 from Miamiohlibs/dev

version 2.4.0 - admin web console

Author: kenirwin

.gitignore

@@ -12,3 +12,4 @@ config/appConf.js
 config/campusConf.js
 config/jamf.js
 
+www/.next/*

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.4.0 - 2024-10-30
+
+### Added
+
+- New feature: Web-based admin console, including System Status, Logs, and Stats. Uses Express.js and EJS. This is an optional feature not required to run the core license management scripts functionality, but should make it easier to monitor and troubleshoot the system. Setting up the admin console requires additional configuration steps, added as an "admin" property. See the [documentation](https://miamiohlib.gitbook.io/software-checkout/setup/admin-web-console) for details.
+
+### Changed
+
+- Updated logEachCheckout, getUsageData, and anonymizeStats to be cron-friendly (no longer requires the user to be in the same directory being evaluated).
+
+## 2.3.0 - 2024-06-12
+
+### Added
+
+- New feature: "demo" scripts allow user to manually add, remove, and list license assignments in LibCal and Jamf on the command line. Also allows lookup of reservations in LibCal, and manage known email aliases.
+
+### Changed
+
+- Jamf uses bearer token for authentication instead of username and password.
+- More consistent log format.
+- Improved error handling for stats functions and emailConverter.
+- Expanded documentation.
+
+## 2.2.0 - 2023-08-15
+
+### Changed
+
+- Adobe API uses Oauth2 for authentication instead of deprecated JWT.

CITATION.cff

@@ -28,5 +28,5 @@ keywords:
   - springshare
   - libcal
 license: GPL-3.0
-version: 2.2.0
-date-released: '2023-08-15'
+version: 2.4.0
+date-released: '2024-10-30'

config/appConf.sample.js

@@ -3,6 +3,29 @@ module.exports = {
     secret: 'you should replace this with gibberish of your own',
     note: 'this is used to encrypt the user data in the logs',
   },
+  admin: {
+    onServer: false,
+    server: {
+      key: '/path/to/public_key.key',
+      cert: '/path/to/certificate.crt',
+      note: 'if onServer is true, you need to provide the key and cert paths',
+    },
+    port: 3010,
+    requireLogin: true,
+    allowedUsers: [], // list allowed emails here
+    apiKey: 'writeYourOwnKeyHereTheValueIsNotImportant',
+    hostname: 'localhost', // or 'your.hostname.edu'
+    googleClientId:
+      'get a google client id from https://console.developers.google.com/apis/credentials',
+    googleClientSecret: 'get a google client secret from the same place',
+    authCallback: 'http://localhost:3010/google/callback', // listed as "Authorized redirect URIs" in the google console
+    navbarTheme: {
+      // see Bootstrap 5 docs for explanation of these color classes:
+      // https://getbootstrap.com/docs/5.0/utilities/background/
+      backgroundColor: 'bg-secondary', // opts: bg-primary, bg-secondary, bg-success, bg-danger, bg-warning, bg-info, bg-light, bg-dark
+      textColor: 'navbar-dark', // use 'navbar-light' for light backgrounds, 'navbar-dark' for dark backgrounds
+    },
+  },
   emailConverter: {
     active: false, // set to true to use the email converter, values below also need to be configured
     baseUrl: 'https://yourEmailConverterApi/?q=',

dailyUsageSummary.js

@@ -1,84 +1,14 @@
-const fs = require('fs');
-const config = require('./config/appConf');
-let software = config.software;
-let softwareTitles = software.map((item) => item.libCalName);
-let allData = [];
-const { Parser } = require('json2csv');
-
-// softwareTitles = ['Adobe Creative Cloud', 'Logic Pro'];
-
-let json = summarizeStats(softwareTitles);
-// console.log(JSON.stringify(json, null, 2));
-const parser = new Parser();
-const csv = parser.parse(json);
-console.log(csv);
-
-function summarizeStats(softwareTitles) {
-  softwareTitles.forEach((softwareTitle) => {
-    let folder = softwareTitle.replace(/ /g, '');
-    // get all files that aren't directories
-    let files, anonFiles;
-    if (fs.existsSync(`./logs/dailyStats/${folder}`) != false) {
-      files = fs.readdirSync(`./logs/dailyStats/${folder}`, {
-        withFileTypes: true,
-      });
-      try {
-        anonFiles = fs.readdirSync(`./logs/dailyStats/${folder}/anon`, {
-          withFileTypes: true,
-        });
-      } catch (err) {
-        anonFiles = [];
-      }
-      files.push(...anonFiles); // all files, anonymous and not
-      files = [...new Set(files)]; // remove duplicates
-      files = files.filter((file) => file.isFile()); // remove directories
-      files.sort((a, b) => (a.name > b.name ? 1 : -1)); // sort by date
-      files.forEach((file) => {
-        let date = file.name.split('.')[0];
-        let usage = getDateStats(softwareTitle, date);
-        updateOrAddEntry({ date, softwareTitle, usage });
-      });
-    }
-  });
-  return allData;
-}
-
-function updateOrAddEntry(newEntry) {
-  let found = false;
-
-  for (let i = 0; i < allData.length; i++) {
-    if (allData[i].date === newEntry.date) {
-      allData[i][newEntry.softwareTitle] = newEntry.usage;
-      found = true;
-      break;
-    }
-  }
-
-  if (!found) {
-    let obj = { date: newEntry.date, [newEntry.softwareTitle]: newEntry.usage };
-    allData.push(obj);
-  }
-}
-
-function getDateStats(softwareTitle, date) {
-  let folder = softwareTitle.replace(/ /g, '');
-  let filepath = './logs/dailyStats/' + folder + '/' + date + '.json';
-  let anonpath = './logs/dailyStats/' + folder + '/anon/' + date + '.json';
-  let data;
-  if (fs.existsSync(filepath)) {
-    data = require(`./logs/dailyStats/${folder}/${date}.json`);
-  } else if (fs.existsSync(anonpath)) {
-    data = require(`./logs/dailyStats/${folder}/anon/${date}.json`);
-  } else {
-    console.log('No file found for ' + softwareTitle + ' on ' + date);
-    return;
+const dailyStatsService = require('./services/dailyStatsService');
+const yargs = require('yargs');
+const argv = yargs(process.argv.slice(2)).argv;
+
+const allowedFormats = ['json', 'csv']; // allowed formats
+if (argv.format) {
+  if (!allowedFormats.includes(argv.format)) {
+    console.log('Invalid format. Use json or csv');
+    process.exit(1);
   }
-  let confirmedBookings = data.filter((item) => item.status == 'Confirmed');
-  let skipCheckins = confirmedBookings.filter(
-    (item) => !item.toDate.match(date + 'T00:00:00')
-  );
-  let distinctUsers = [...new Set(skipCheckins.map((item) => item.email))];
-  let totalUsage = distinctUsers.length;
-  // console.log(softwareTitle + ',' + date + ',' + totalUsage);
-  return totalUsage;
+  console.log(dailyStatsService(argv.format));
+} else {
+  console.log(dailyStatsService());
 }

docs/README.md

@@ -2,6 +2,8 @@
 
 **Software Checkout** is a Node.js app for libraries and other institutions to allow dynamic request and assignment of software licenses. Users can request license access by signing up for a time-slot using SpringShare's [LibCal](https://www.springshare.com/libcal/); the app then updates license assignments with the vendor's user management API to assign or a revoke licenses at the appropriate time.
 
+The main Software Checkout app does not have its own web interface, but there is an admin web console to provide an easy way for admins to check on the status of license assignments, usage statistics, and examination of system logs.
+
 ## Current Supported Vendors
 
 * [Adobe Creative Cloud](https://www.adobe.com/creativecloud.html)

docs/SUMMARY.md

@@ -6,8 +6,9 @@
   * [LibCal](setup/libcal.md)
   * [Adobe](setup/adobe.md)
   * [Jamf](setup/jamf.md)
+  * [Admin Web Console](setup/admin-web-console.md)
   * [Component Demos/Tests](setup/component-demos-tests.md)
-* [Running the App](running-the-app.md)
+* [Running the App & Admin Web Console](running-the-app-and-admin-web-console.md)
 * [Testing](testing.md)
 * [Usage Stats](usage-stats.md)
 * [Troubleshooting](troubleshooting/README.md)

docs/running-the-app-and-admin-web-console.md

@@ -0,0 +1,27 @@
+# Running the App & Admin Web Console
+
+### Running the app
+
+There are several ways to run the app from the command line:
+
+* `node app` - run once
+* PRODUCTION: `npm run server`: will add the `--listen` flag as well as `--name=software-checkout` so we can see which node process it is
+* `node jamfUserUpdate` - for unknown reasons, the process for adding Jamf users wasn't working in the main app, so we spun it off as its own process that should run prior to running the app. It should be run _before_ the main app.
+
+#### Running as a cron job
+
+The app just runs once when you run one of the above commands. To make the service useful, you should run it frequently -- every 10-15 minutes. Set up a cron job to run the service in production a few times an hour, and run the jamfUserUpdate before it (if using Jamf):
+
+`1,13,25,37,49 * * * * /usr/bin/node /opt/dev/SoftwareCheckout2/jamfUserUpdate.js > /dev/null 2>&1` \
+`2,14,26,38,50 * * * * /usr/bin/node /opt/dev/SoftwareCheckout2/app.js --name=Software-Checkout > /dev/null 2>&1` 
+
+You will likely want to run the daily stats update as a cron job too -- that is described in the [Usage Stats](usage-stats.md) page.
+
+#### Killing / restarting the app
+
+* run `./killapp` -- finds the relevant process and kills it (only works if you used `npm run server` to start the app
+* `./restart` or `./killapp -r`: kill and restart (or use `npm run server` as above)
+
+## Running the admin web console
+
+Unlike the main app, which runs as a "headless" process with no native user interface, the admin web console is a web-based service. For information on setting up and running the web process see [Express Web Setup](setup/admin-web-console.md#express-server-setup).

docs/running-the-app.md

@@ -14,6 +14,17 @@ Request API keys from LibCal and Adobe. You will enter these values in the confi
 
 * `config/appConf.js`:
   * `cryptoConfig`: The value defined here will be used as an encryption key to keep any anonymized data encrypted, while keeping values consistent so you can identify the number of distinct users of the system over time. Change the `cryptoConfig.secret` value to any random long string when you set up the app. You should not change it afterwards. 
+  * `admin:` setup of the admin web console, including authentication details, port number, and server information.
+    * `onServer:` use `false` for running over http://localhost, `true` for https:// on a server
+    * `server:` https key/cert pair
+    * `port:` port on which Express will listen for web calls; default is 3010
+    * `requireLogin:` whether or not to require Google login for users to access the admin web console. Only set this to `false` when running on localhost and/or for debugging purposes. Should be set to `true` in production.
+    * `allowedUsers:` array of permitted users; if `requiredLogin: true`, user email must be included in this array to access the web admin console.
+    * `apiKey:` This is the API key required to access the API that powers the admin web console. Make this value up for yourself, the app uses it to authenticate to its own API. You will only need it if you want to connect to the web admin console API externally. 
+    * `hostname:` set to 'localhost' or the server address without protocol (e.g. 'sc.lib.myorg.edu')
+    * googleClientId: create a googleClientId from the Google Develop Console: [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials)
+    * googleClientSecret: this will be generate when you generate the googleClientId
+    * authCallback: you will set this value in the Google Developer Console. Set it to a value like 'http://localhost:3010/google/callback' or 'https://sc.lib.yourorg.edu:3010/google/callback' -- use the server and port you've specified above + '/google/callback'.
   * `db_connection`: mongodb connection string (optional; used for caching converted email aliases)
   * `logLevels`: for each level, set one of: false, 'daily', 'monthly'; false for no logs at that level; 'daily' for logs that start a new logfile each day; 'monthly' for a new logfile per year. Use daily logs for levels that output obnoxiously large amounts of data like 'debug'. Currently, only 'info','error', and 'debug' are used by the app.
   * `emailConverter`: LibCal may accept users' aliased email addresss (e.g. my.full.name@fake.org) even though license providers may only use the uniqueId version of a user Id (e.g. namemf@fake.org). If your organization has an API that will convert email aliases to the uniqueId/authoritative email address, use these settings to configure the use of the API.