search

Exercise 6: Building a custom Appsody Stack Collection in Kabanero

In this exercise, we will show how to create a custom Collection, that includes the custom Appsody Stack from the previous exercise.

When you have completed this exercise, you will understand how to

  • clone and host your own Collection

  • modify the Collection to include a custom Appsody Stack

Tools used during Exercise 6

hashtag
Prerequisites

You should have already carried out the prerequisites defined in Exercise 5. In addition, you need to ensure you have the following installed on your local machine:

  • yq

  • python3

  • pyYAML

On macOS, you can install the above with:

NOTE: do not install the python yq package, it has a different syntax than the yq application and will cause the build scripts to fail.

hashtag
About custom Kabanero Repositories

By default the Kabanero open source project is configured to automatically use the latest release at https://github.com/kabanero-io/collectionsarrow-up-right.

The default collections can be modified to meet an organization's unique needs.

  • Collections are categorized as either stable, incubator or experimental depending on the content of the collection.

    • stable: collections that meet a set of technical requirements.

    • incubator: collections that are actively being worked on to satisfy the stable criteria.

    • experimental: collections that are used for trying out specific capabilities or proof of concept work.

  • Collections include an Appsody stack, and a Tekton pipeline.

hashtag
Steps

  1. Create a new repo to host your custom collection

  2. Create a new image namespace to host images on OpenShift

  3. Set up a local build environment

  4. Add our custom stack to the new collection

  5. Build the new collection

  6. Push collection images

  7. Update code repo and release a new collection

hashtag
1. Create a new repo to host your custom collection

Go to https://github.com/newarrow-up-right and create a new repository, collections. Do not initiatize the repos with a license file or README.

New repo

Clone the default collections repository and create a new copy of it in your GitHub organization, replacing <username> with your own.

hashtag
About the Kabanero Repo structure

hashtag
2. Create a new image namespace to host images on OpenShift

To actually use the stacks we need images, images will be hosted on openshift

NOTE: You may seem a warning about this step, but it should still have worked, e.g.

hashtag
3. Set up a local build environment

There are several environment variables that need to be set up. These are required in order to correctly build the collections.

NOTE: When setting the TRAVIS_REPO_SLUG variable, make sure you substitute the actual github repo you created above in place of <username>.

In addition to the above, the IMAGE_REGISTRY environment variable should still be set from Exercise 3, which you can check with:

If IMAGE_REGISTRY is not set, then you need to set it up again, as described in Exercise 3 - Access the internal docker registry

hashtag
4. Add our custom stack to the new collection

Now we take our custom stack from exercise 5 (recall that is was named my-nodejs-express and includes the helmet library) and copy it over to the incubator folder of our collection repo. From the collections repo, perform the following steps:

List the collections before the copy:

Now copy in our new custom stack:

Check that we now have this in the list of collections:

Create a new file called collection.yaml in collections/incubator/my-nodejs-express, add the following:

Edit the new file called stack.yaml in collections/incubator/my-nodejs-express. Update the name and description fields to add "with Helmet" and also replace the maintainer information with your information if desired (you will probably see a different version, don't change that and keep as-is):

And also create a directory called pipelines in collections/incubator/my-nodejs-express, and add a single empty file called .gitkeep.

hashtag
5. Build the new collection

This step builds the kabanero-index.yaml file.

From the collections directory, run the build script. For example:

NOTE: This process can take several minutes to complete.

Note that this will build all the collections in the incubator directory, including the new my-nodejs-express stack.

Following the build, you can find the generated collection assets in the collections/ci/assets/ directory and all the docker images in your local docker registry.

You should see output like the following, take note of the my-nodejs-express stack being built, and ensure there are no errors in the output:

hashtag
6. Push collection images

To push the collection images, there is a release script that will do the actual pushing to the image registry. The current scripts have a minor issue with private registry login and tagging so first log in to the private registry, and then run the release script. The two commands below will achieve this:

You should see output like the following, take note of the my-nodejs-express stack being pushed to the registry, and ensure there are no errors in the output:

NOTE: Since this above is pushing a lot of images, it is possible that you might see this command fail with a timeout error, or unknown blob. Retrying the command (more than once if necessary) will resolve this issue.

hashtag
7. Update code repo and release a new collection

Once you have made all the changes to the collection and you are ready to push the changes back to your git repository then

To create a full release of the collections, create a git tag:

Navigating back to your GitHub repo, you should see a new release available:

Our own collection, version 0.2.1-custom

Clicking on the release name (0.2.1-custom) will allow you to edit the release.

Our own collection, page for version 0.2.1-custom

Click on Edit tag. and then upload all the files in collections/ci/release/ which were generated from the previous steps, by clicking on the Attach binaries... box.

Our own collection, upload files to release

Once you have uploaded the files you can publish your new collection by clicking Publish release, at the bottom of the page

Our own collection, published

You will note that the collection includes the kabanero-index.yaml file we edited earlier. The url to this index file is is what you will provide appsody as a link to your new custom repository (that is contained within the new collection. You normally obtain and copy the url (depending on your browser) by right (or secondary) clicking over the kabanero-index.yaml item in the list of files shown in the release. It should be of the form:

https://github.com/<username>/collections/releases/download/0.2.1-custom/kabanero-index.yaml

You will need this url for the next exercise, where we will create an appsody application based on your new collection.

Congratulations!! We've just created our own custom collection that included our own custom stack. Now we need to test our released collection using Appsody. On to the next exercise.

PreviousExercise 5: Customizing an existing Appsody StackNextExercise 7: Using a custom collection with Appsody

Last updated

Was this helpful?