solacedev/solace-dev-codelabs

Specific repo housing codelabs that are part of the Solace Codelabs

Solace Codelabs

The purpose of these codelabs is to create easily consumable, step-by-step tutorials that walk a developer to achieve a goal.

This repository is included as a submodule in the main site repo. The main codelabs site is deployed from that repo and codelab artifacts are kept here.

Directories

• codelabs - contains codelabs that will be served up on https://codelabs.solace.dev/. The raw markdown file is exported into this directory via the claat tool.
• markdown - This directory contains the markdown file that the codelabs were generated from.

How to Contribute

Prepare your repository

1. Fork this main repository by clicking on the Fork button on the top right
2. From a terminal window, clone your fork of the repo git clone [email protected]:<Your_Github_User>/solace-dev-codelabs.git
3. Navigate to the newly cloned directory cd solace-dev-codelabs
4. Checkout a local branch for your new codelab git checkout -b add-codelab-<name_of_codelab>

Option 1 - Script

1. Setup your environment
2. Read the solace guidelines
3. From the root directory, run ./init.sh <name-of-codelab> script
4. Navigate to /markdown/name-of-codelab
5. Run the following from terminal npm install; npm run watch
6. Edit your <name-of-codelab>.md file in your text editor of choice
7. When ready, run export.sh
8. Navigate to the codelabs root directory (cd ../../), add and commit your changes in a PR. From the root directory,

cd ../../ #to navigate to the root of the codelabs dir
git add .
git commit -m "add new codelab: <name of codelab>"
git push origin add-codelab-<name_of_codelab>

Note: origin in the command above the name of the remote repository. If your remote repository is of a different name then you will have to git push <name_of_remote_repo> add-codelab-<name_of_codelab>

Option 2 - Manual

Follow the steps in this tutorial: https://codelabs.solace.dev/codelabs/codelab-4-codelab

Note: original markdown of this codelab is found under codelabs/codelab-4-codelab

Learn About CodeLab

• CodeLabs are being created using Google Codelabs: https://github.com/googlecodelabs/tools

solace-dev-codelabs's Issues

Fix Broken Links

Broken Links checker found some missing links during the last PR.
This links should either be removed or updated.

https://github.com/SolaceDev/solace-dev-codelabs/runs/2401499891?check_suite_focus=true

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Codelab-4-codelabs enhancement

• Edit content to call out preferred way to authoring codelabs (automation)
• Add guidance for tech reviewer
• Add guidance local experience video

Add script to create new codelab from template

The idea here is to create a new folder in the markdown dir with

1. .md file with the header presetup
2. export.sh script that includes the claat export with ga code in it
3. Update codelab-4-codelab steps

Codelab-4-Codelabs bugs

1. Rather than have download link be: https://github.com/SolaceDev/solace-dev-codelabs/blob/master/markdown/codelab-4-codelab/codelab-4-codelab.md (which gets formatted to HTML by github), link to https://raw.githubusercontent.com/SolaceDev/solace-dev-codelabs/master/markdown/codelab-4-codelab/codelab-4-codelab.md

2. Add a windows environment section? Go can be downloaded here https://golang.org/dl/, claat is the same link to binaries.

3. Update feedback link

Add PR review process

Once the PR is up, trigger a github action that comments on the PR showing the review process guidelines

e.g.
[ ] Tag reviewer
[ ] Review Technical content

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

📝 Summary
---------------------
🔍 Total...........26
✅ Successful......23
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........2
🚫 Errors...........1

Errors in https://codelabs.solace.dev/
✗ https://solace.community/categories/pubsub%2B-tutorials (HTTP status client error (404 Not Found) for url (https://solace.community/categories/pubsub%2B-tutorials))

Full Github Actions output

Automation enhancement

Temp Dir

Right now, npm run watch will export the codelab to a temp dir. It is only deleted upon ./export.sh. We have to find a way to either

• Delete it on stopping the watch
• Add it to a gitignore temp dir

Deps

• Install deps if not present (MacOS + Windows)

Modifications to How to Event-Enable your REST Architecture codelab

• Add docs sections https://docs.solace.com/Overviews/Microgateway-Concepts/Microgateways-Overview.htm
• Update curl command with double quotes
• Fix turoial typo

Update Takeaways Image

Please update the takeaways page w/ a smaller Solly image. I imagine most people will just remove the giant one that takes up the entire screen 😛

I would recommend this one: https://codelabs.solace.dev/codelabs/design-to-code-workshop/index.html?index=..%2F..index#8

Change PubSubPlus to PubSub+ in title of Kubernetes Operator Codelab

Change "PubSubPlus" to "PubSub+" in title of Kubernetes Operator Codelab

https://codelabs.solace.dev/codelabs/solace-k8s-operator/index.html?index=..%2F..index#0

Update the Boomi getting started codelab

The boomi getting started codelab does not have secure connection steps. This issue is to modify the codelab and follow the same steps here
https://dev.to/swenhelge/securely-connecting-to-solace-cloud-from-boomi-4506

Install Claat does not work

I tried with the go get command, I tried with go install command, I tried downloading the binary, nothing works. Can you update the codelab with working steps to show how to install claat?

Automation Enhancement - Add takeaways template as last section

I think we should add a default "Takeaways" section at the end of the generated template to remind people to do a quick recap and also to make sure we always have a community call-out.

Maybe something like this which I'm using for the codelab I'm currently working on?

Takeaways

Duration: 0:03:00

• ✅ < FIILL IN TAKEAWAY 1>
• ✅ < FIILL IN TAKEAWAY 2>
• ✅ < FIILL IN TAKEAWAY 3>

Thanks for participating in this codelab! Let us know what you thought in the Solace Community Forum and if you found any issues along the way we'd appreciate it if you'd raise them by clicking the Report a mistake button at the bottom left of this codelab.

Remove all references to our GA property ID

Hi Team,
As discussed, we have our Google Analytics (GA) Property ID being loaded twice;

1. We have it being loaded within our Google Tag Manager (GTM) container, which is served via Netlify's Snippet Injection.
2. We also have it being loaded separately via Codelabs themselves.

Due to (2.) we're noticing the following, which is causing our analytics to be polluted;

• anyone who clones/forks the Codelabs repo then has our GA ID within their copy.
• anyone working locally, is also being tracked in GA, as we're seeing localhost in our analytics.
• there's also references to netlify which I'm assuming is from previews being viewed.

For the reasons above we need to remove any and all references to GA UA-3921398-10 from Codelabs as soon as we can, in order to ensure we're getting the most accurate analytics.

Thanks again.

Replace reference to "Open Support Ticket" in A Solace Primer Codelab

Identified by @TKTheTechie here: https://solacedotcom.slack.com/archives/C2E9XN0JZ/p1633976363006100

"Open Support Ticket" is not an option for free trial users. Please replace direction in step 10 of "A Solace Primer - Getting Started with Solace PubSub+ Event Broker" codelab to use the "Chat With Us" option. + replace screenshot.

Link Checker Report

Errors were reported while checking the availability of links.

📝 Summary
---------------------
🔍 Total...........26
✅ Successful......23
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........2
🚫 Errors...........1

Errors in https://codelabs.solace.dev/
✗ https://solace.community/categories/pubsub%2B-tutorials (HTTP status client error (404 Not Found) for url (https://solace.community/categories/pubsub%2B-tutorials))

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Review Be Real-Time: Design, Document, Discover and Develop Event-Driven APIs

This should be done after #120

Review Be Real-Time: Design, Document, Discover and Develop Event-Driven APIs codelab. The GUI has changed and some of the screenshots need to be updated. Please quickly run through the codelab and make sure it works. Also check codelab for formatting.

There also seems to be a formatting issue on Step 6 when creating the PaymentCharged schema.

Update Design to Code Codelab to use more recent AsyncAPI Generator version

Update Design to Code Codelab to use more recent AsyncAPI Generator version that 0.53.1. The latest should now work with EP.

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Category Fixes

Before we get too many codelabs let's make sure the categories make sense.

Suggestions:

• Both Helm codelabs should also have Kubernetes
• Should the raspberry pi one show up under javascript?

Another issue with Java Part of the https://codelabs.solace.dev/codelabs/design-document-discover-develop-event-driven-apis

Hi,

Sorry for remark, but it is pretty frustrating to have a step-by-step lab that doesn't work. I've made a Solace course where, if I recall it right, the lab was mentioned there.

Anyway, the exported AsyncAPI file and description for code generation doesn't work at all. TL;TW - just try to get the Java code compiled by following the description and you'll meet all the issues.

Add git basics to Contribute instructions

Because many contributors are not used to git we need to add the “git fork, git clone, git add, git commit, git push” steps to the solace-dev-codelab README file

Auto Staging preview on PR

On PR, create a netlify staging preview against site repo

Link Checker Report

Errors were reported while checking the availability of links.

📝 Summary
---------------------
🔍 Total...........26
✅ Successful......23
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........2
🚫 Errors...........1

Errors in https://codelabs.solace.dev/
✗ https://solace.community/categories/pubsub%2B-tutorials (HTTP status client error (404 Not Found) for url (https://solace.community/categories/pubsub%2B-tutorials))

Full Github Actions output

Cannot export AsyncAPI Definition

Hi,

In the step 10, https://codelabs.solace.dev/codelabs/design-document-discover-develop-event-driven-apis/index.html?index=..%2F..index#10 attempting to download AsyncAPI definition and get:

An error occurred
The event PaymentCharged has a topic that will not work with AsyncAPI. Topic addresses must only contain letters, numbers and one or more of the following special characters: !#$&()*+,-./:;=[]_~.

Could it be a problem with Async API 2.0.0., because in the tutorial the generator should be installed in the version 0.53.1 that doesn't work properly either.

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Review Codelabs for use of unsecure ports

As Solace Cloud now disables unsecure ports (such as 55555) by default we should update codelabs to use secured ports where feasible and/or show how to enable unsecure ports during setup.

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

📝 Summary
---------------------
🔍 Total...........26
✅ Successful......23
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........2
🚫 Errors...........1

Errors in https://codelabs.solace.dev/
✗ https://solace.community/categories/pubsub%2B-tutorials (HTTP status client error (404 Not Found) for url (https://solace.community/categories/pubsub%2B-tutorials))

Full Github Actions output

Consider adding PDF Functionality

Consider adding PDF functionality.
Essentially save the codelab as a pdf and providing a link in the overview of each codelab to the PDF in case that format is preferred.

Thread discussing technical steps for how to do this (still a WIP)
https://groups.google.com/forum/#!topic/codelab-authors/pnnY50o82Qw

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

broken link in boomi-v2-getting-started.md

In "Steps to get started with Boomi", in "Setup Boomi environment", the link to Environment Management Boomi User Guide.
Visiting that link gives a page that says "The topic you are attempting to view does not exist."
This might be the new link: https://help.boomi.com/bundle/integration/page/c-atm-Environment_management.html
Hmm, it is the same except for the random char blob at the end.

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Add image compression in automation

in the ./export.sh script, include a step to iterate over all the assets in the img dir and compress all the images
For example
https://www.npmjs.com/package/compress-images

Notes:

1. Once an npm package is installed, the cli executable can be accessed from node_modules/<name_of_package>/bin
2. Rename compressed images to -compress. (or similar) to avoid recompressing already compressed images
3. Add exception handling to image extensions that is not supported by the compression cli tool. There are alot of weird extensions for images

Consider adding code copying capability

It would be great to have the ability to copy & paste code by clicking a button the code snippet.

Started the conversation here to see what others come up with: https://groups.google.com/forum/#!topic/codelab-authors/NvFv9LJ9LvI

Update EP App Domain Import Screens

Update App Domain Import Screens

• Import button has been removed
• Now have to click "toolkit" + choose application domains
• they now ask for the Logical Event Mesh

This will need to be updated in every codelab that imports an App Domain file

To avoid extra user input we should ensure that a logical event mesh is specified in the export files.

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Modify claat cli to accept customized iframe whitelist

More info here https://groups.google.com/forum/#!topic/codelab-authors/GXR8B5VCgww

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output

Add unit tests CI/CD

Unit tests include

• Checking GaCode in markdown and html
• Confirm header matches convention
• Add 404 URL checker

Link Checker Report

Errors were reported while checking the availability of links.

📝 Summary
---------------------
🔍 Total...........26
✅ Successful......23
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........2
🚫 Errors...........1

Errors in https://codelabs.solace.dev/
✗ https://solace.community/categories/pubsub%2B-tutorials (HTTP status client error (404 Not Found) for url (https://solace.community/categories/pubsub%2B-tutorials))

Full Github Actions output

Link Checker Report

Errors were reported while checking the availability of links.

Full Github Actions output