Appsody provides pre-configured application stacks that enable rapid development of quality microservice-based applications. Stacks include a base container image and project templates, which provide the language runtimes, frameworks, and any additional libraries and tools that you need for local development. Stacks are an easy way to manage consistency and adopt best practices across many applications.
Appsody uses a containerized environment during local development. The stack image defines this environment and specifies the stack behavior during the development lifecycle of the application.
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.
Each Appsody stack is defined by a common set of source directories and files. The following example shows the structure for a stack called my-stack
:
my-stack
├── README.md # describes the contents of the stack and how it should be used
├── stack.yaml # defines the different attributes of the stack and which template the stack should use by default
├── image/
| ├── config/
| | └── app-deploy.yaml # configuration file for deploying an Appsody project using the Appsody Operator
| ├── project/
| | ├── [files that provide the technology components of the stack]
| | └── Dockerfile # defines the final image that will created by the appsody build command
│ ├── Dockerfile-stack # defines the foundation stack image, and a set of environment variables for the local development cycle
| └── LICENSE
└── templates/
├── my-template-1/
| └── [example files as a starter for the application, e.g. "hello world"]
└── my-template-2/
└── [example files as a starter for a more complex application]
The image
directory contains files for the stack image. The image/Dockerfile-stack
Dockerfile defines the exact steps for building the stack image. Dockerfile-stack
builds the initial stack image for local development and the Dockerfile
builds the final application image. They are independent of each other.
The templates
directory contains one or more starter applications that are created for you when you initialize your projects. Every template is contained within its own directory, /templates/<template-name>
.
.appsody-config.yaml
is not part of the source structure. It is generated as part of the stack building process and is placed in the user directory by the appsody init
command. This file specifies the stack image that is used and can be overridden for testing purposes to point to a locally built stack.
Appsody stacks belong to one of three categories, depending on their stability level. The criteria for each category is detailed in the following sections:
These stacks are not production-ready and are considered as proof of concept. They might be unstable, and subject to breaking changes. Experimental stacks must meet the following criteria:
These stacks are not production-ready and require further development to satisfy the stable criteria. Incubator stacks must meet all the criteria set for experimental stacks and the following additional items:
README.md
These stacks are production-ready. Stable stacks must meet all the criteria set for experimental and incubator stacks, and the following additional items:
stack.yaml
yum upgrade
, apt-get dist-upgrade
, npm audit fix
). If a package contained in the parent image is out of date, contact its maintainers or update it individually.Follow Docker best practices, including:
Include a detailed README.md
, documenting:
Below are the URLs for official Appsody repository releases.
Repository | URL |
---|---|
stable |
https://github.com/appsody/stacks/releases/latest/download/stable-index.yaml |
incubator |
https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml |
experimental |
https://github.com/appsody/stacks/releases/latest/download/experimental-index.yaml |
By default, Appsody comes with the incubator
and experimental
repositories. Other repositories can be added by running the appsody repo add
command.
The following steps outline the process for contributing a new stack or changes to a stack:
The Stack Contributor submits a pull request with changes to a stack. The pull request should follow commit guidelines detailing the stack changes. If the change improves the stack stability level, the pull request must also describe how the new criteria for that level is met (e.g. how Docker best practices have been implemented).
The Stack Maintainer(s) (as listed in the stack.yaml
) review the pull request, keeping in mind the stability criteria of the stack. If the Stack Maintainer(s) are satisfied that the stack changes follow the stability criteria, the pull request gets approved.
Note: If the stack is new, the Stack Release Team reviews the pull request and decides if the stack satisfies the chosen stability criteria.
The Stack Release Team merges and releases the new stack. When the stack is released: