FP-1496: CSS Build to Core-Styles

.gitignore

@@ -16,7 +16,6 @@ build
 !build/README.md
 
 ## environment variables
-.env
 docker_repo.var
 
 # Static and Media folders
@@ -26,7 +25,6 @@ docker_repo.var
 repo_name.var
 
 # Secrets and Customizations
-settings.json
 taccsite_cms/secrets.py
 *.custom.yml
 *settings_custom*.py

Dockerfile

@@ -63,4 +63,7 @@ COPY . /code
 WORKDIR /code
 
 # build assets
-RUN npm ci && npm run build
+RUN npm ci
+ARG PROJECT_NAME
+ARG BUILD_ID
+RUN npm run build --project=$PROJECT_NAME --build-id=$BUILD_ID

Makefile

@@ -1,5 +1,7 @@
 DOCKERHUB_REPO := taccwma/$(shell cat ./docker_repo.var)
+PROJECT_NAME := $(shell cat ./docker_repo.var)
 DOCKER_TAG ?= $(shell git rev-parse --short HEAD)
+BUILD_ID := $(shell git describe --always)
 DOCKER_IMAGE := $(DOCKERHUB_REPO):$(DOCKER_TAG)
 DOCKER_IMAGE_LATEST := $(DOCKERHUB_REPO):latest
 
@@ -9,7 +11,7 @@ build:
 
 .PHONY: build-full
 build-full:
-	docker build -t $(DOCKER_IMAGE) --target production -f ./Dockerfile .
+	docker build -t $(DOCKER_IMAGE) --target production --build-arg PROJECT_NAME=$(PROJECT_NAME) --build-arg BUILD_ID=$(BUILD_ID) -f ./Dockerfile .
 
 .PHONY: publish
 publish:

README.md

@@ -7,6 +7,7 @@ The base CMS code for TACC WMA Workspace Portals & Websites
 
 - [Camino], a Docker container-based deployment scheme
 - [Core Portal], the base Portal code for TACC WMA CMS Websites
+- [Core CMS Styles], the custom UI pattern code for TACC WMA CMS Websites
 - [Core CMS Resources], the custom CMS code for TACC WMA CMS Websites
 - [Core Portal Deployments], private repository that facilitates deployments of [Core Portal] images via [Camino] and Jenkins
 
@@ -35,21 +36,12 @@ After you clone the repository locally, there are several configuration steps re
 
 #### Required
 
-1. Create a `.env` file\*† at the root of the project with this content:
-
-    ```bash
-    CUSTOM_ASSET_DIR=name-of-project
-    ```
-
-1. Initialize / Update submodules.
+1. Initialize / Update submodules:
     1. `git submodule init`\
         <sub>Adds [Core CMS Resources] repo as submodule at `taccsite_custom/`. Only necessary once per parent repo clone.</sub>
     2. `git submodule update`\
         <sub>Downloads code from pinned commit of [Core CMS Resources] repo to `taccsite_custom/`.</sub>
 
-<sub>\* A ["dotenv" file](https://hexdocs.pm/dotenvy/dotenv-file-format.html) is a file, with or without a name, that has the `.env` extension.</sub>\
-<sub>† Where `name-of-project` matches a directory from `/taccsite_custom`.</sub>
-
 #### Optional
 
 Settings may be customized piecemeal by adding, in any of these files, only the settings to change:
@@ -76,8 +68,7 @@ Follow [How to Use a Custom Docker Compose File](https://github.com/TACC/Core-CM
 All CMS projects (besides the stand-alone CMS core), store project-specific resources in the `taccsite_custom` submodule.
 
 1. Create a `taccsite_cms/settings_custom.py` symlink to `taccsite_custom/name-of-project/settings_custom.py`.\*†
-2. Update the `.env` file so `CUSTOM_ASSET_DIR=name-of-project`.\*
-3. Build project-specific static files. _See [Static Files](/README.md#static-files)._
+2. Build project-specific static files. _See [Static Files](/README.md#static-files)._
 
 <sub>\* Where `name-of-project` matches a directory from `/taccsite_custom`.</sub>\
 <sub>† Example (from project root): `ln -s ../taccsite_custom/name-of-project/settings_custom.py taccsite_cms/settings_custom.py`\*</sub>
@@ -187,21 +178,26 @@ If you changes files in any `static/` directory, you may need to follow some of
 #### Quick Start
 
 0. _(assumed)_ Install missing or out-of-date Node dependencies.\*
-1. _(optional)_ Make changes to `/taccsite_custom/name-of-project/static/name-of-project/css/src` files.\†‡
+1. _(optional)_ Make changes to `/taccsite_custom/name-of-project/static/name-of-project/css/src` files. †‡
 2. Build static files from source files.\
     Via shell:
-    1. `npm run build` or\
-        `npm run build --project=name-of-project`\†
+    1. `npm run build`\
+        or\
+        `npm run build --project=name-of-project` †\
+        or\
+        `npm run build (...) --build-id=optional-identifier` §
 3. _(to debug)_ Review respective files' content in\
-    `/taccsite_custom/name-of-project/static/name-of-project/css/build`.\†
+    `/taccsite_custom/name-of-project/static/name-of-project/css/build`. †
 4. "Collect" static files. _See [How to Collect Static Files](#how-to-collect-static-files)._
-5. _(to debug)_ Confirm respective output changed in\
-    `/taccsite_cms/static/site_cms/css/build` and/or\
-    `/taccsite_custom/static/name-of-project/css/build`.\†
+5. _(to debug)_ Confirm respective output changed in:\
+    `/taccsite_cms/static/site_cms/css/build`\
+    and/or\
+    `/taccsite_custom/static/name-of-project/css/build` †
 
 <sub>\* The recommended command to install expected dependencies is `npm ci`.</sub>\
 <sub>† Where `name-of-project` matches a directory from `/taccsite_custom`.</sub>\
-<sub>‡ To commit such changes, see [Changing Custom Resources](#changing-custom-resources)</sub>
+<sub>‡ To commit such changes, see [Changing Custom Resources](#changing-custom-resources).</sub>\
+<sub>§ A build ID can tag files (e.g. preserved comment in stylesheet).</sub>
 
 #### How to Build Static Files
 
@@ -338,6 +334,7 @@ Sign your commits ([see this link](https://help.github.com/en/github/authenticat
 [Core Portal Deployments]: https://github.com/TACC/Core-Portal-Deployments
 [Camino]: https://github.com/TACC/Camino
 [Core CMS]: https://github.com/TACC/Core-CMS
+[Core Styles]: https://github.com/TACC/Core-Styles
 [Core CMS Resources]: https://github.com/TACC/Core-CMS-Resources
 [Core Portal]: https://github.com/TACC/Core-Portal
 [1]: https://docs.docker.com/get-docker/

bin/build-css-via-cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/** Build CSS using the Core-Styles CLI */
+
+const fs = require('fs');
+const cmd = require('node-cmd');
+const mininmist = require('minimist');
+
+const ROOT = __dirname + '/..';
+const CORE_NAME = 'core-cms';
+const ARGS = mininmist( process.argv.slice( 2 ) );
+
+const PROJECT_NAME = ARGS['project'] || '';
+const BUILD_ID = ARGS['build-id'] || '';
+
+/** Build stylesheets for Core and (optional) project */
+(() => {
+  // Get style paths
+  const corePath = _getPath('taccsite_cms', 'site_cms');
+  const projPath = _getPath(`taccsite_custom/${PROJECT_NAME}`, PROJECT_NAME );
+  const hasProject = ( PROJECT_NAME && PROJECT_NAME !== CORE_NAME );
+
+  // Get config paths
+  const coreConfPath = `${ROOT}/${corePath}/.postcssrc.yml`;
+  const projConfPath = `${ROOT}/${projPath}/.postcssrc.yml`;
+  const confPaths = [coreConfPath];
+
+  // Always add relevant available project config
+  // FAQ: Project can customize Core build (e.g. theme changes CSS env. values)
+  if ( hasProject && fs.existsSync( projConfPath ) ) {
+    confPaths.push( projConfPath );
+  }
+
+  // Build
+  _build('Core', corePath, confPaths, BUILD_ID );
+  if ( hasProject ) {
+    _build( PROJECT_NAME, projPath, confPaths, BUILD_ID );
+  }
+})();
+
+/**
+ * Execute command to build stylesheets
+ * @param {string} name - The name of the project
+ * @param {string} path - The path to the project source CSS
+ * @param {array.string} configs - The list of config file paths
+ * @param {string} id - The value to identify the build
+ */
+ function _build( name, path, configs, id ) {
+  const configValues = '"' + configs.join('" "') + '"';
+
+  console.log(`Overriding config with:`, configs );
+  console.log(`Building "${name}" styles:`);
+  cmd.runSync(`
+    core-styles build\
+    --input-dir "${ROOT}/${path}/src"\
+    --output-dir "${ROOT}/${path}/build"\
+    --custom-configs ${configValues}\
+    --build-id "${id}"\
+    --verbose\
+  `);
+}
+
+/**
+ * Get path to CSS resources
+ * @param {string} dirName - The name of the directory
+ * @param {string} [subDirName=dirName] - The name of the sub-directory
+ * @return {string}
+ */
+ function _getPath( dirName, subDirName ) {
+  return dirName + '/static/' + ( subDirName || dirName ) + '/css';
+}