Add a Glossary page which defines Appsody specific terms

[helenmasters]

There are plenty of Appsody-specific terms (and commonly used terms which mean something specific in the context of Appsody) it would help users if they could go somewhere to find a definition of any terms they find confusing. In our discussion about content it was decided that it would be helpful to add a Glossary page to the website.

The glossary needs to be alphabetical and include newly introduced, uncommon, or Appsody specialized wording.

Proposed starting list for the glossary. The list definitely needs to be much longer!

• [x] Appsody @neeraj-laad
• [x] Appsody CLI
• [x] Appsody controller @chilanti
• [x] Appsody operator
• [ ] CI/CD pipelines
• [ ] cloud functions @sympatheticmoose
• [ ] cloud native @sympatheticmoose
• [ ] cloud packaged @sympatheticmoose
• [ ] deployment manifest
• [ ] Docker / Docker image?
• [x] Dockerfile
• [x] Dockerfile-stack
• [ ] Knative / Knative service?
• [ ] Kubernetes
• [x] stack / Appsody stack @neeraj-laad
• [ ] Tekton pipelines
• [x] template / Appsody template @neeraj-laad
• [ ] stack hub

[helenmasters]

@sympatheticmoose - please can you add definitions for cloud functions, cloud native and cloud packaged.

[Kamran64]

Can we add Dockerfile-stack to the list as well? I've seen a few times people ask what's the difference between that and the Dockerfile

[chilanti]

Appsody controller seems to be missing.

[helenmasters]

Thanks @chilanti I've added Appsody controller.

[neeraj-laad]

Could/should we add a few words on:

• Appsody repository
• Appsody repository index

[helenmasters]

Attempts to define Dockerfile and Dockerfile-stack for the Glossary: @neeraj-laad and @sympatheticmoose - comments please.

Dockerfile

In Appsody, a Dockerfile that defines how a stack image is built by Docker for production. During application development, the stack image is built by a different Dockerfile, Dockerfile-stack. Dockerfile-stack contains environment variables that are read and interpreted by the Appsody CLI and Appsody controller to provide the expected behavior for the developer.

Dockerfile-stack

A definition here too? or a straight link into the above definition?

A Dockerfile that specifies the behavior of a stack throughout the application development lifecycle, by using Appsody environment variables. or Defines how the stack image is built by Docker for application development.

Also do we want to include sentences like "The Dockerfile-stack is used by the Appsody run, test, and debug commands." and "The Dockerfile is used by the Appsody build and deploy commands." within these definitions, or is this level of detail too much (or indeed likely to change) as I personally found that helpful to understand what was going on when I first encountered these files?

[helenmasters]

First set of definitions obtained for review:

Appsody

Appsody is an open source project that simplifies developing applications for Kubernetes. It includes pre-configured runtimes and frameworks as ‘Stacks’, which allow you to easily package existing applications in best-practice Dockerfiles, or create new applications and functions, which are ‘cloud-native’ from the moment you start. These can then be deployed to Kubernetes or as scale-to-zero serverless containers through Knative, with a single command. Stacks are easily customisable and allow teams to embed their own expertise and help others get productive faster.

My comments - best-practice? can we claim that? scale-to-zero I find confusing These it isn't clear in the third sentence what it's referring to. I think the last sentence in italics should be removed.

[helenmasters]

Appsody CLI

The Appsody CLI supports the full application development lifecycle, from creating new ‘Stacks’ and applications, through testing and debugging, and deployment to Kubernetes.

My comments - I think we should change 'Stacks' to a reference to stacks that points to the stacks definition. Is it clear in the above that the 'applications' are based on these stacks?

[helenmasters]

Dockerfile and Dockerfile-stack Dockerfile-stack is a [Dockerfile]() that builds the base container image of a stack and specifies its behavior during development.

Dockerfile combines your application and the stack to build a production image, ready for deployment. 

[helenmasters]

Project Templates

These typically provide a 'Hello World' starting point for application development. As with other components within an Appsody stack, they are customizable by developers and can be shared across teams.

[sympatheticmoose]

scale-to-zero I find confusing

@helenmasters I understand the confusion, its tricky to be clearer whilst keeping the descriptions short - and this is the commonly used way of describing the behaviour - i.e. https://github.com/knative/serving

[helenmasters]

Appsody stack

Appsody stacks are pre-configured language runtimes, frameworks, and additional libraries and tools to simplify application development. Stacks are an easy way to manage consistency and adopt best practices across many applications. [They can be customised by individual developers, or development teams, to suit their needs]. Stacks include a base container image (see [Dockerfile-stack]()) and [project templates]() that act as a starting point for your application development.

[doveye]

Appsody stack

Appsody stacks are pre-configured language runtimes, frameworks, and additional libraries and tools to simplify application development. Stacks are an easy way to manage consistency and adopt best practices across many applications. [They can be customised by individual developers, or development teams, to suit their needs]. Stacks include a base container image (see Dockerfile-stack) and project templates that act as a starting point for your application development.

I don't think the contents of a stack is entirely clear from this. Also, should we mention cloud here, eg "application development for the cloud" or "cloud-native application development", since this is specifically what Appsody is for? (As I understand it anyway!) How about this (not entirely sure of technical accuracy, and it's longer!)

An Appsody stack is a collection of components, such as language runtimes, frameworks, libraries, and tools, that simplifies application development for the cloud. A stack includes a base container image (see Dockerfile-stack), and project templates that act as a starting point for application development. As a stack provider, you can customise a stack to suit your needs before making it available to your developers, thereby improving consistency and best practices across applications. As a developer, stacks enable you to create and test cloud-ready applications without having to worry about the underlying container technology.

[doveye]

Project Templates

These typically provide a 'Hello World' starting point for application development. As with other components within an Appsody stack, they are customizable by developers and can be shared across teams.

• To be consistent, lower-case t in Templates
• What's typical - the "Hello world", or the starting point? If the latter, is there a case where a starting point isn't provided?
• Could be more active voice?

How about:

Project templates provide a starting point, typically a 'Hello World' application, for application development. Like other components within an Appsody stack, you can customize project templates and share them across teams.

Just a thought - do we mean "project" templates? Sounds like we're actually talking about "application" templates, but maybe "project" makes more sense in an IDE?

[SueChaplain]

Appsody CLI

The Appsody CLI supports the full application development lifecycle, from creating new ‘Stacks’ and applications, through testing and debugging, and deployment to Kubernetes.

The Appsody CLI supports the full application development lifecycle; creating stacks, creating applications based on stacks, testing, debugging, and deploying to Kubernetes.

Hmm

[doveye]

Re the CLI, I think it's worth spelling out "command-line interface", just to be clear :)

[doveye]

Dockerfile and Dockerfile-stack Dockerfile-stack is a Dockerfile that builds the base container image of a stack and specifies its behavior during development.

Dockerfile combines your application and the stack to build a production image, ready for deployment.

Think it's worth mentioning Docker here, and pointing to their docs for more info about Dockerfiles. Suggested rewrite (I've made the names code as they seem to relate to filenames rather than a concept?), though I think the env vars bit needs clarification - maybe an example? It's currently not clear why two different files are used:

Dockerfile and Dockerfile-stack

A Dockerfile is a text file that defines how a container image is built by Appsody's underlying container technology, Docker [link to Dockerfile definition?]. In Appsody, Dockerfile-stack defines how your stack is built for application development (when you run the test or debug commands, for example). Dockerfile defines how your stack is built for deployment (when you run the build or deploy commands, for example). The main difference is that Dockerfile-stack includes environment variables that provide expected behavior for developers.

[helenmasters]

Appsody CLI

The Appsody CLI supports the full application development lifecycle, from creating new ‘Stacks’ and applications, through testing and debugging, and deployment to Kubernetes.

The Appsody CLI supports the full application development lifecycle; creating stacks, creating applications based on stacks, testing, debugging, and deploying to Kubernetes.

Hmm

I'm not sure why but the "testing, debugging, and deploying" written like this doesn't feel like it applies to the apps, whereas it did with the first incarnation. Is the following any clearer?

The Appsody command-line interface supports the full application development lifecycle; creating stacks, creating applications based on stacks, through testing, debugging, and deploying your apps to Kubernetes.

[doveye]

The Appsody command-line interface supports the full application development lifecycle; creating stacks, creating applications based on stacks, through testing, debugging, and deploying your apps to Kubernetes.

How about: "The Appsody command-line interface supports the full application development lifecycle; creating stacks, creating applications based on stacks, testing and debugging your applications, and deploying your applications to Kubernetes."

Which is basically two changes - "applications" instead of "apps" (not sure how important that is really - everyone uses "apps" these days) and separating out Kubernetes as "debugging your apps to Kubernetes" sounds odd :) Or, if you want to include Kubernetes with the testing/debugging:

"The Appsody command-line interface supports the full application development lifecycle; creating stacks, creating applications based on stacks, and testing, debugging, and deploying your applications on Kubernetes."

[helenmasters]

We will need definitions in the Glossary for cloud packaged, cloud native and cloud functions if we are going to reference these as options to filter on from the new Stacks page, so here are some first pass notes which I've gathered from elsewhere (thanks David Harris):

Cloud Functions

Provide a 'Functions-as-a-Service' programming model. You can think of it as similar to AWS lambda, however - the key difference is that lambdas are their own 'thing', they have their own SDK and are very proprietary tech. With our implementation developers can use the APIs they are already using in traditional apps, so there is less of a learning curve/jar in the experience. For Java, you can write JAX-RS functions, in Node.js you write to 'Connect' which is what Express (web framework) uses. So developers are already familar with writing the function handler - only now that's all they need to write.

Can we shorten this to...

Provides a 'Functions-as-a-Service' programming model, so that developers can use APIs that they are already using in existing applications. For example, in Java, you can write JAX-RS functions; in Node.js you can write to 'Connect' which the Express (web framework) uses.

? Do we need wording something like "The developer writes simple functions that are uploaded into the cloud and executed independently" in the shorter version above?

Cloud Native

Includes a pre-configured web framework, such as Express or Liberty, and provides a number of endpoints that help with cloud deployments, such as health (liveness and readiness), and monitoring, or metrics.

Is the above description enough... personally I find the notes below really helpful in addition?

Cloud Native - as a term - we describe as applications which leverage the services provided by a cloud platform. So if your cloud (i.e. IBM Cloud) uses Prometheus monitoring, your apps should integrate with that. Given nearly all clouds are aligning around Kubernetes - this is the base point. Health Checks are how Kubernetes knows whether your app can have work routed towards it, or if it needs restarting.

Cloud Packaged 

Allows you to take an application, wrapper it in a best practice Dockerfile and deploy to your cloud. [It is basically a black box.? HM - I don't think this second sentence is helpful.]

[SueChaplain]

I think Cloud Functions needs to mention server-less in some way.

• developers write independent server-less functions that are deployed to the cloud. Functions can be loosely coupled to provide reactive applications.

Not even sure that is technically accurate, but hoping the words might help evolve what we have so far.

[doveye]

I think these definitions need to explain what the term is - is it a component of Appsody? Is it just a descriptive term (as "cloud native" appears to be). If they are not actual "things", the second word shouldn't be capitalized. For example, "Cloud Packaged - allows you to..." - what is it that allows you? "Cloud Native - includes..." - what is it that includes ...? A dictionary would say something like (eg for "Cloud native"):

• (of applications) designed and built to use the services of a cloud
• Pertaining to applications that are designed and built to use the services of a cloud

I assume "Cloud Functions" doesn't refer to any of the Cloud Function packages that various vendors have if you look online. If it's a general term that has a specific meaning in Appsody, you could start the definition with that, ie "In Appsody, a functions-as-a-service (FaaS) programming model that enables developers to use APIs that they are already using in existing applications." Though it's still not clear to me what this means - do you mean program your apps using the familiar APIs? Or do cloud-specific stuff with them?

[sympatheticmoose]

All have a specific meaning within Appsody as they refer to specific levels/flavours of stacks. They are based on common-ish terminology, hence with functions multiple vendors describing their offerings as such.

[neeraj-laad]

Let us look at adding Appsody, Appsody Stack, Appsody controller and Appsody Operator to the Glossary and the rest can wait and get added when we have a need to add them.

[SueChaplain]

First pass ....... for discussion / evolution / correction :-) .......

Appsody

Appsody is an IBM open source project that provides tools to help users develop containerized applications for the cloud.

Appsody stacks

Appsody stacks contain software components that provide the foundation for building applications that run in containers. Stacks are available for different language runtime environments and frameworks, which can be customized to suit local needs.

Appsody controller

The controller manages a running application inside a development container, watching for changes in the application source and restarting the application when new changes are saved.

Appsody operator

The operator controls the deployment of applications that are developed using Appsody to Kubernetes environments.

[helenmasters]

Appsody controller

The controller manages a running application inside a development container, watching for changes in the application source and restarting the application when new changes are saved.

I feel like this one needs a few more words - I'd like it to say "inside the Appsody development container" along with some words about that being the container that is started when developers run, debug or test their applications, or am I being pedantic and that's obvious?

Appsody operator

The operator controls the deployment of applications that are developed using Appsody to Kubernetes environments. +1 for operator definition

[neeraj-laad]

Appsody

Appsody is an open source project that provides tools to help users develop and deploy containerized applications for the cloud.

Appsody controller

The controller manages a running application inside the Appsody development container. It monitors file changes in the application source and provides live updates to the application running in the container.

Appsody operator

The operator manages the deployment of applications that are developed using Appsody to Kubernetes environments.

[SueChaplain]

@neeraj-laad @helenmasters

Stack hub is being used as a term at Kabanero and they asked if this was defined at Appsody. We are using this in the Overview, so should probably add this to the Glossary too. I updated the list in the description.

Appsody Hub The Hub is the central point of control for Appsody Stacks where you can find available stacks, create new stacks, or modify existing ones. There are 3 stack stability levels - stable, incubator, and experimental. Stable stacks are production-ready. You can use the Hub content in the public repo or clone it to provide a private Hub that's based on your requirements. By making changes to the Stacks in the Hub, you can deploy updates to any application that's been built on them, simply by restarting the application. You can also create individual stacks outside of the Hub, that can be supported by the Appsody CLI.

Appsody hub An Appsody hub, or stack hub, is the central point of control for Appsody stacks. The public hub contains all the available stacks from the Appsody project. When you clone the public hub, you create a local hub for managing or maintaining your own stacks.

What do you think? Too much information? Too close to what we have in the overview?

Revision (maybe?): An Appsody hub, or stack hub, is the central point of control and storage for Appsody stacks. A hub can be public (https://github.com/appsody/stacks.git) or local (cloned and customized).

[helenmasters]

I prefer the "revision" but I've asked Matt Kilner for comments as he has a foot in both Appsody and Kabanero.

[kilnerm]

Having talked to Neeraj I believe there is a possibility of Appsody Hub being deprecated from the vocabulary. I also don't understand what anyone means by a stack hub, as far as I can see it is an unnecessary definition as in my mind all they are referring to is an index containing more then a single stack. Do we have a description of what a Stack hub is?

[SueChaplain]

At the moment we have Appsody Hub front and centre in the overview, so that will need addressing. I think what we want to convey is "the place where you keep all your appsody stack definitions", which is I guess, just a repo?

[kilnerm]

The Appsody hub is where people can contribute their stacks. If they wish to maintain their own then I expect they would have a single stack per source repository. In the latter scenario if someone wanted to consolidate their collection of stacks they would merge all the index files into a master index.

I can see an acceptable definition of the Appsody hub as being the place to come and see stacks that have been contributed. But I don't see what a stack hub is or why it is needed.

[SueChaplain]

I can see an acceptable definition of the Appsody hub as being the place to come and see stacks that have been contributed. But I don't see what a stack hub is or why it is needed.

That's fine. We should add Appsody Hub to the glossary for the public stacks, but won't refer to stack hubs or what they should call their customized collections. We will change the terminology used upstream.