prebuild dev container (#20)

* using prebuilt container from a different repo

* prebuild dev container to improve first run perf

* only push docs after merge or on demand

* support .devcontainer/root.pem self-signed cert

* update readme with instructions

* use TROLIE project links

* add some more detail on local editing

* docs url cleanup

* use containerEnv to manage private repo proxies

* update readme with private package repo proxy instructions

* remove unused image

* remove extraneous comment

* add comment and commit executable bit

* background jekyll on devcontainer startup

* enable livereload for jekyll

---------

Co-authored-by: Christopher Atkins <[email protected]>

.devcontainer/devcontainer.json

@@ -1,33 +1,20 @@
 {
-	"name": "TROLIE devcontainer",
-	"build": {
-        "dockerfile": "Dockerfile"
+    "name": "TROLIE devcontainer",
+    "image": "ghcr.io/trolie/spec-devcontainer:latest",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-azuretools.vscode-docker",
+                "Redocly.openapi-vs-code",
+                "emeraldwalk.RunOnSave"
+            ]
+        }
     },
-	"features": {
-		"ghcr.io/devcontainers/features/common-utils:2": {
-			"upgradePackages": true,
-			"username": "vscode",
-			"userUid": "automatic",
-			"userGid": "automatic"
-		}
-	},
 
-	"remoteUser": "vscode",
-
-	"customizations": {
-		"vscode": {
-			"extensions": [
-				"ms-azuretools.vscode-docker",
-				"Redocly.openapi-vs-code",
-				"emeraldwalk.RunOnSave"
-			]
-		}
-	},
-
-    // this path is used by the redocly cli
-    "workspaceMount": "source=${localWorkspaceFolder},target=/spec,type=bind",
-    "workspaceFolder": "/spec",
-
-	"postCreateCommand": "cd /spec/docs && bundle install",
-	"postStartCommand": "cd /spec/docs && bundle update github-pages && bundle exec jekyll serve"
+    "postCreateCommand": ".devcontainer/post.sh create",
+    "postStartCommand": ".devcontainer/post.sh start",
+    "containerEnv": {
+        "GEM_REPO": "https://rubygems.org",
+        "NPM_CONFIG_REGISTRY": "https://registry.npmjs.org"
+    }
 }

.devcontainer/post.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+PARENT="$(dirname "$SCRIPT_DIR")"
+if [[ ! $# -eq 1 ]]; then 
+    echo "either 'create', 'start', or 'bundle' should an the argument"
+    exit 0
+fi
+
+CERT_PATH=$SCRIPT_DIR/root.pem
+
+if [ -s $CERT_PATH ]; then
+    echo "Using SSL_CERT_DIR=$CERT_PATH"
+    export SSL_CERT_DIR=$CERT_PATH
+fi
+
+DOCS_PATH="$PARENT/docs"
+
+if [[ "${1,,}" == "create" ]]; then
+    # see https://www.kenmuse.com/blog/avoiding-dubious-ownership-in-dev-containers/
+    git config --global --add safe.directory $PARENT
+
+    cd $DOCS_PATH && bundle install
+    exit 0
+fi
+
+if [[ ("${1,,}" == "bundle") || ("${1,,}" == "start") ]]; then
+    npx --yes @redocly/cli bundle $DOCS_PATH/_data/openapi-split.yaml -o $DOCS_PATH/openapi.yaml
+fi
+
+if [[ "${1,,}" == "start" ]]; then
+    cd $PARENT/docs && bundle update && nohup bundle exec jekyll serve  --force_polling --livereload > $PARENT/jekyll.out 2>&1 &
+    sleep 4
+    tail $PARENT/jekyll.out
+    echo "Jekyll started, to monitor see $PARENT/jekyll.out"
+fi

.github/.devcontainer/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:lts-slim
+
+RUN set -eux; \
+	apt update -y -qq && apt install -y -qq ruby-full build-essential \
+	&& gem install bundler;
+
+USER node
+
+RUN gem install --user-install github-pages webrick \
+	&& ln -s $(ruby -r rubygems -e 'puts Gem.user_dir')/bin ~/.local/bin \
+	&& echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

.github/.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+	"name": "TROLIE spec devcontainer",
+	"build": {
+        "dockerfile": "Dockerfile"
+    },
+	"features": {
+		"ghcr.io/devcontainers/features/common-utils:2": {
+			"upgradePackages": true
+		}
+	}
+}

.github/workflows/openapi-bundle.yaml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - '1.0.0-wip'
+      - 1.0.0*
 
 permissions:
   contents: read

.github/workflows/prebuild.yaml

@@ -0,0 +1,30 @@
+name: Dev Container Build and Push Image
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 1.0.0*
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Checkout
+        id: checkout
+        uses: actions/checkout@v3
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Pre-build dev container image
+        uses: devcontainers/[email protected]
+        with:
+          imageName: ghcr.io/trolie/spec-devcontainer
+          cacheFrom: ghcr.io/trolie/spec-devcontainer
+          push: always
+          subFolder: .github

.gitignore

@@ -5,4 +5,6 @@ _site/
 .jekyll-metadata
 # Ignore folders generated by Bundler
 .bundle/
-vendor/
+vendor/
+.devcontainer/root.pem
+jekyll.out

.vscode/settings.json

@@ -5,7 +5,7 @@
             {
                 "match": "docs/_data/*",
                 "isAsync": true,
-                "cmd": "npx --yes @redocly/cli bundle /spec/docs/_data/openapi-split.yaml -o /spec/docs/openapi.yaml"
+                "cmd": ".devcontainer/post.sh bundle"
             }
         ]
     }

README.md

@@ -2,14 +2,40 @@
 
 Transmission Ratings and Operating Limits Information Exchange
 
-[OpenAPI Specification docs](https://ge-grid-software.github.io/TROLIE/)
+[OpenAPI Specification docs](https://TROLIE.github.io/spec/)
 
 ### License
 
-[Apache 2.0](https://github.com/ge-grid-software/TROLIE/blob/main/LICENSE)
+[Apache 2.0](https://github.com/TROLIE/spec/blob/1.0.0-wip/LICENSE)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/white/lf-energy-project-horizontal-white.png">
   <source media="(prefers-color-scheme: light)" srcset="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/color/lf-energy-project-horizontal-color.png">
   <img alt="Official LF Energy Project logo" src="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/color/lf-energy-project-horizontal-color.png" width="200">
 </picture>
+
+## Specification Editors
+
+The `docs/` folder contains a Jekyll site for the GH Pages along with the yaml
+that is used with `redocly bundle` to created the OpenAPI specification.
+
+To simply the local setup of the toolchain, a devcontainer is provided. This
+will also install VS Code extensions to help with local editing as well.
+
+If your company uses MITM, self-signed certificates through your Internet proxy
+and/or proxies upstream RubyGem or npm repos, please follow the instructions in
+the next section.
+
+### Self-Signed Certs and Repo Proxies
+
+Put your company's self-signed cert in a PEM file at: `.devcontainer/root.pem`
+
+You can use your company's RubyGem and npm proxies by specifying them in
+`.devcontainer\devcontainer.json` by replacing:
+
+```json
+  "containerEnv": {
+      "GEM_REPO": "https://rubygems.org",
+      "NPM_CONFIG_REGISTRY": "https://registry.npmjs.org"
+  }
+```

docs/Gemfile

@@ -1,4 +1,4 @@
-source "https://rubygems.org"
+source ENV['GEM_REPO']
 
 gem "github-pages", "~> 228", group: :jekyll_plugins
 

docs/index.md

@@ -9,12 +9,12 @@ title: Home
 
 # {{site.data.openapi-split.info.title}}
 
-[OpenAPI Specification docs](https://ge-grid-software.github.io/TROLIE/)
+[OpenAPI Specification docs](./redocly.html)
 
 ### License
 
-[Apache 2.0](https://github.com/ge-grid-software/TROLIE/blob/main/LICENSE)
 
+[Apache 2.0](https://github.com/TROLIE/spec/blob/1.0.0-wip/LICENSE)
 <picture>
   <img alt="Official LF Energy Project logo" src="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/color/lf-energy-project-horizontal-color.png" width="200">
 </picture>