From 43dc1de049312958e2472c1d2eae32ca10ef9f0c Mon Sep 17 00:00:00 2001 From: Matthew Bystedt Date: Wed, 8 May 2024 14:48:37 -0700 Subject: [PATCH 1/3] docs: improve readme and clarify local usage --- README.md | 62 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 9297752..a5cce53 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,57 @@ # NR Repository Composer -NR Repository Composer provides convenient way to launch generators to scaffold applications using NRIDS tooling and deployment pipelines. The generators are created using [Yeoman](http://yeoman.io) and packaged into a docker container for running on a developer's machine. +NR Repository Composer provides convenient way to launch generators to scaffold applications using NRIDS tooling and deployment pipelines. The generators are created using [Yeoman](http://yeoman.io). For distribution, it is packaged into a docker container for running on a developer's machine. # Prerequisites -## Podman or Docker +There are two ways to run the composer. -The generators are easiest to run by installing Podman or Docker so that you can use the prebuilt container (ghcr.io/bcgov-nr/nr-repository-composer). +## Run using a Container + +You will need to install one of the following. * [Podman](https://podman.io) * [Docker](https://www.docker.com) -# Usage - Podman - -First, open a terminal and change the current working directory to the root of the checked out repository that you wish to scaffold. The examples map the current working directory to the '/src' directory inside of the container which is the directory the generator outputs to. +The generators are easiest to run by installing Podman or Docker so that you can use the prebuilt container (ghcr.io/bcgov-nr/nr-repository-composer). -It is recommended that you run the generators only on a clean repository. +It is recommended that users running Windows install the command locally or use Podman. Docker cannot modify the file permissions correctly on mounted volumes. As such, the example commands will not work. -The generator will output a file saving your answers. This is useful if you want to rerun the generator in the future to take advantage of any updated workflows. +## Run using a local install -This command will run the 'gh-maven-build' generator: +You will need to install node and clone this repository. -``` -podman run --rm -it -v ${PWD}:/src --userns keep-id ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build -``` +* [Node 20](https://nodejs.org/en) -Note: You can run the command with or without the generator specified. +The tool is build using [Yeoman](http://yeoman.io) which is a JavaScript library. You do not need to install Yoeman. -# Usage - Local +Install the dependencies with `npm ci` and link it with `npm link` so Yoeman can find the local installation. If you make code changes, you do not need the re-link it. ```bash npm ci npm link ``` -Then, run a generator: +# Usage + +First, open a terminal and change the current working directory to the root of the checked out repository that you wish to scaffold. It is recommended that you run the generators only on a clean repository. + +The generators will output a file to save your answers and will update any `app-config.yaml` catalogue file. This is useful if you want to rerun the generator in the future to take advantage of any updated workflows. + +The example command will run the 'gh-maven-build' generator. + +### Container + +``` +podman run --rm -it -v ${PWD}:/src --userns keep-id ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build +``` +``` +docker run --rm -it -v ${PWD}:/src ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build +``` + +The examples map the current working directory to the '/src' directory inside of the container which is the directory the generator outputs to. + +### Local ```bash npx yo nr-repository-composer:gh-maven-build @@ -42,19 +59,20 @@ npx yo nr-repository-composer:gh-maven-build ## Generators -### Github Maven Build: gh-maven-build +All generators are built to be rerun multiple times. -The generator, gh-maven-build, generates the CI workflow and NR Broker intention files for building Java/Tomcat with Maven in GitHub. +### Backstage: backstage + +The generator, backstage, generates a app-config.yaml catelogue file. -Answer the prompts: +### Github Maven Build: gh-maven-build -1. Project name (e.g. my-app) -2. Service name (e.g. my-app-war) -3. OpenShift Artifactory project (default: cc20) -4. Maven pom file root (default: repository root) +The generator, gh-maven-build, generates the CI workflow and NR Broker intention files for building Java/Tomcat with Maven in GitHub. The generated files will appear in your .github/workflows and .jenkins directories. +The option `--promptless` can be used with this command to attempt to run it without prompting for responses. It will attempt to only used information stored in your `app-config.yaml`. This option can be combined with `--force` which will let Yoeman automatically overwrite any existing files. + # Developing Generators ## Requirements From fd094485181c9b56c0bef55d5449b381f22cc3b5 Mon Sep 17 00:00:00 2001 From: Matthew Bystedt Date: Wed, 8 May 2024 14:50:25 -0700 Subject: [PATCH 2/3] chore: grammar --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a5cce53..b7bac86 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ The generator, gh-maven-build, generates the CI workflow and NR Broker intention The generated files will appear in your .github/workflows and .jenkins directories. -The option `--promptless` can be used with this command to attempt to run it without prompting for responses. It will attempt to only used information stored in your `app-config.yaml`. This option can be combined with `--force` which will let Yoeman automatically overwrite any existing files. +The option `--promptless` can be used with this command to attempt to run it without prompting for responses. It will attempt to only use information stored in your `app-config.yaml`. This option can be combined with `--force` which will let Yoeman automatically overwrite any existing files. # Developing Generators From 5a91ec9d4df1a2bf51b9672604baacfca0df0ecd Mon Sep 17 00:00:00 2001 From: Matthew Bystedt Date: Wed, 8 May 2024 15:04:31 -0700 Subject: [PATCH 3/3] chore: grammar --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b7bac86..62da5bc 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ All generators are built to be rerun multiple times. ### Backstage: backstage -The generator, backstage, generates a app-config.yaml catelogue file. +The generator, backstage, generates a `app-config.yaml` catalogue file. ### Github Maven Build: gh-maven-build