feat: build and publish container images for easy integration (#620)

* feat: Containerfile to create image from current source

Signed-off-by: Matthias Blümel <[email protected]>

* feat: Build and publish container images for easy integration

* Run test-docker in CI with a valid IBM ruleset extension
* Add docs for container image use on README
* Add deploy step to push images

Signed-off-by: John Starich <[email protected]>

---------

Signed-off-by: Matthias Blümel <[email protected]>
Signed-off-by: John Starich <[email protected]>
Co-authored-by: Matthias Blümel <[email protected]>

Author: JohnStarich

.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+Dockerfile
+.git

.travis.yml

@@ -15,6 +15,7 @@ before_install:
 script:
 - npm run test-travis
 - npm run lint
+- npm run test-docker
 
 deploy:
 - provider: script
@@ -23,3 +24,10 @@ deploy:
   on:
     node: 18
     branch: main
+- provider: script
+  skip_cleanup: true
+  script: ./scripts/deploy.sh "$TRAVIS_TAG"
+  on:
+    node: 18
+    all_branches: true
+    condition: $TRAVIS_TAG =~ ^ibm-openapi-validator@.*$

Dockerfile

@@ -0,0 +1,24 @@
+FROM node:18-alpine
+LABEL org.opencontainers.image.source="https://github.com/IBM/openapi-validator"
+LABEL org.opencontainers.image.documentation="https://github.com/IBM/openapi-validator#container-image"
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.title="OpenAPI Validator"
+LABEL org.opencontainers.image.description="The IBM OpenAPI Validator lets you validate OpenAPI 3.x documents according to the OpenAPI 3.x specification, as well as IBM-defined best practices."
+
+WORKDIR /src
+# Copy and cache dependencies first for faster local rebuilds.
+COPY ./package.json ./package-lock.json /src/
+COPY ./packages/ruleset/package.json /src/packages/ruleset/package.json
+COPY ./packages/validator/package.json /src/packages/validator/package.json
+COPY ./packages/utilities/package.json /src/packages/utilities/package.json
+RUN npm ci
+
+# Add validator to executable $PATH for easy integration in custom downstream images.
+ENV PATH=/usr/local/lib/node_modules:$PATH
+# Add IBM ruleset to Node module search path for easy volume mounts and ruleset extensions.
+ENV NODE_PATH=/usr/local/lib/node_modules
+COPY . /src
+RUN npm run link
+
+WORKDIR /data
+ENTRYPOINT ["/usr/local/bin/lint-openapi"]

README.md

@@ -35,6 +35,8 @@ and [OpenAPI 3.1.x](https://github.com/OAI/OpenAPI-Specification/blob/master/ver
   * [Download an executable binary](#download-an-executable-binary)
   * [Build from source](#build-from-source)
     + [Build platform-specific binaries](#build-platform-specific-binaries)
+  * [Container image](#container-image)
+    + [Building your own](#building-your-own)
 - [Usage](#usage)
   * [Command Syntax](#command-syntax)
   * [Configuration](#configuration)
@@ -105,6 +107,44 @@ _If you installed the validator using `npm install -g ibm-openapi-validator`, yo
 #### Build platform-specific binaries
 It is also possible to build platform specific binaries from the source code by running `npm run pkg` in the project root directory.  The binaries (lint-openapi-macos, lint-openapi-linux, lint-openapi-windows.exe) will be in the project's `packages/validator/bin` directory.
 
+### Container image
+
+Run the validator with the container image by mounting your API definition.
+
+If it is named `openapi.yaml` in the current directory, then run:
+```bash
+docker run \
+  --rm --tty \
+  --volume "$PWD:/data:ro" \
+  ibmdevxsdk/openapi-validator:latest \
+    openapi.yaml
+```
+
+You should **replace `latest` with a specific tagged version** to avoid any surprises when new releases are published.
+
+Flag and argument syntax is the same as described in [Usage](#usage), but file paths are relative to `/data`.
+
+To use a custom ruleset named `ruleset.yaml` in the current directory, run:
+```bash
+docker run \
+  --rm --tty \
+  --volume "$PWD:/data:ro" \
+  ibmdevxsdk/openapi-validator:latest \
+    --ruleset ruleset.yaml \
+    openapi.yaml
+```
+
+#### Building your own
+
+If the existing image doesn't suit your needs, you could extend it and build your own.
+
+For example, to build a validator image with your own custom ruleset package installed, make a `Dockerfile` like this:
+
+```Dockerfile
+FROM ibmdevxsdk/openapi-validator:latest
+RUN npm install -g ${your-ruleset-pkg-here}
+```
+
 ## Usage
 ### Command Syntax
 ```bash

package.json

@@ -11,16 +11,18 @@
   "repository": "https://github.com/IBM/openapi-validator",
   "scripts": {
     "clean": "rm -rf node_modules/ && npm run clean --workspaces",
+    "build-docker": "docker build -t ibmdevxsdk/openapi-validator:latest .",
     "test": "npm run test --workspaces",
     "test-ruleset": "npm run test --workspace packages/ruleset",
     "test-utilities": "npm run test --workspace packages/utilities",
     "test-validator": "npm run test --workspace packages/validator",
+    "test-docker": "npm run build-docker && docker run --rm --volume \"$PWD\"/packages/validator/test/cli-validator/alternate-spectral-configs/extends-default.yaml:/data/ruleset.yaml --volume \"$PWD\"/packages/validator/test/cli-validator/mock-files/oas3/clean.yml:/data/openapi.yaml ibmdevxsdk/openapi-validator:latest --ruleset ruleset.yaml openapi.yaml",
     "jest": "jest",
     "test-travis": "npm run test-travis --workspaces",
     "lint": "npm run lint --workspaces",
     "fix": "npm run fix --workspaces",
     "pkg": "npm run pkg --workspace packages/validator",
-    "link": "npm run link --workspace packages/validator",
+    "link": "npm run link --workspace packages/validator --workspace packages/ruleset",
     "unlink": "npm run unlink --workspace packages/validator",
     "all": "npm run test && npm run lint",
     "format-readme-toc": "markdown-toc --maxdepth 5 -i README.md"

packages/ruleset/package.json

@@ -8,6 +8,7 @@
   "repository": "https://github.com/IBM/openapi-validator",
   "scripts": {
     "clean": "rm -rf node_modules",
+    "link": "npm install -g",
     "jest": "jest",
     "test": "jest test",
     "test-travis": "jest --silent --runInBand --no-colors --testNamePattern='^((?!@skip-ci).)*$' test",

scripts/deploy.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+set -e
+
+deploy() {
+    local travis_tag=$1
+    login "$DOCKER_HUB_TOKEN"
+    deploy_docker "$travis_tag"
+}
+
+login() {
+    local token=$1
+    if [[ -z "$token" ]]; then
+        echo 'No Docker Hub token available' >&2
+        exit 2
+    fi
+    docker login --username ibmdevxsdk --password-stdin <<<"$token"
+}
+
+
+deploy_docker() {
+    local tag=$1
+    [[ "$tag" =~ ibm-openapi-validator@([[:digit:]]+\.[[:digit:]]+\.[[:digit:]]+) ]]
+    local docker_tag=${BASH_REMATCH[1]}
+
+    npm run build-docker
+    docker tag ibmdevxsdk/openapi-validator:latest ibmdevxsdk/openapi-validator:"$docker_tag"
+
+    docker push ibmdevxsdk/openapi-validator:"$docker_tag"
+    docker push ibmdevxsdk/openapi-validator:latest
+}
+
+deploy "$@"