beginning toc and filesystem reconfig #2790
Conversation
phillipgibson
requested review from
schristoff,
sgettys and
bdegeeter
as code owners
There was a problem hiding this comment.
A lot of this is just me passing through the documentation (finally) and updating things.
A thing to note is we have
"Introduction, QuickStart, Getting Started, Learn Porter" - which I feel should all be under each other. Maybe like
(H1)Learn Porter
(H2) Introduction
(H2) Quickstart OR Getting Started (probably those can be converged)
I would think giving Mixins and Bundles their own heading, and doing like such
(H1) Mixins
(H2) Working with Mixins
(H2) Developing a Mixin
(H2) Distributing a Mixin
(H1) Bundles
(H2) Inspecting Bundles
(H2) Copy Bundles
I see what you're doing trying to categorize them by actions though, I think we should look at widely used documentation (even if people don't like them) and try to copy what is familiar. Consul, Kubernetes, Kustomize were just three off my head. If engineers are our main consumers of these documents, then high level organizing by piece of product may be the easiest for them.
| description: Create a bundle with Porter | ||
| --- | ||
|
|
||
| Let's walk through how to create and customize your very own Porter bundle. |
There was a problem hiding this comment.
| Let's walk through how to create and customize your very own Porter bundle. |
| --- | ||
|
|
||
| Let's walk through how to create and customize your very own Porter bundle. | ||
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. |
There was a problem hiding this comment.
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. | |
| Bundles include the tools and logic necessary to automate a deployment. |
There was a problem hiding this comment.
I'd add "runtime-environment" or equivalent to the list of what a bundle includes.
|
|
||
| Let's walk through how to create and customize your very own Porter bundle. | ||
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. | ||
| When writing a bundle, it is best if you have already figured out the commands necessary to perform the deployment first, and then use Porter to package that into a bundle. |
There was a problem hiding this comment.
| When writing a bundle, it is best if you have already figured out the commands necessary to perform the deployment first, and then use Porter to package that into a bundle. | |
| When writing a bundle, it's best to have figured out how to perform the deployment first. Then use Porter to package that into a bundle. |
Contractions makes documentation feel more written in a 'human voice' 🤖
There was a problem hiding this comment.
Consider "workflow" over "commands".
There was a problem hiding this comment.
Oh workflow is such a good one, I spent awhile trying to figure that one out
| Let's walk through how to create and customize your very own Porter bundle. | ||
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. | ||
| When writing a bundle, it is best if you have already figured out the commands necessary to perform the deployment first, and then use Porter to package that into a bundle. | ||
| Learning Porter while also figuring out how to deploy a particular application can be difficult. |
There was a problem hiding this comment.
| Learning Porter while also figuring out how to deploy a particular application can be difficult. |
Redundant
| ## Requirements | ||
| You must [install Porter], and optionally can use the [Porter Visual Studio Code] extension for autocomplete while editing the porter.yaml file. | ||
|
|
There was a problem hiding this comment.
| ## Requirements | |
| You must [install Porter], and optionally can use the [Porter Visual Studio Code] extension for autocomplete while editing the porter.yaml file. | |
| ## Requirements | |
| * [Install Porter] | |
| * Optional: [Porter Visual Studio Code] extension | |
| ## Steps |
Gosh I hope this one comes across correctly as a suggestion
| @@ -225,7 +225,7 @@ WORKDIR ${BUNDLE_DIR} | |||
| CMD ["/cnab/app/run"] | |||
| ``` | |||
|
|
|||
| Porter starts the [Dockerfile](/bundle/custom-dockerfile) by using a base image. You can customize the base image by specifying a Dockerfile template in the porter.yaml. By default, Porter only targets a single os/architecture(linux/amd64) for invocation image. If you want to use other platform, feel free to change the platform flag in the generated Dockerfile template. Next, a set of CA certificates is added. Next, contents of the current directory are copied into the bundle directory (/cnab/app) in the invocation image. This will include any contributions from the mixin executables. Finally, an entry point that conforms to the CNAB specification is added to the image. | |||
| Porter starts the [Dockerfile](/bundle/custom-dockerfile) by using a base image. You can customize the base image by specifying a Dockerfile template in the porter.yaml. By default, Porter only targets a single os/architecture(linux/amd64) for invocation image. If you want to use other platform, feel free to change the platform flag in the generated Dockerfile template. Next, a set of CA certificates is added. Next, contents of the current directory are copied into the bundle directory (/cnab/app) in the invocation image. This will include any contributions from the mixin executables. Finally, an entry point that conforms to the CNAB specification is added to the image. | |||
There was a problem hiding this comment.
| Porter starts the [Dockerfile](/bundle/custom-dockerfile) by using a base image. You can customize the base image by specifying a Dockerfile template in the porter.yaml. By default, Porter only targets a single os/architecture(linux/amd64) for invocation image. If you want to use other platform, feel free to change the platform flag in the generated Dockerfile template. Next, a set of CA certificates is added. Next, contents of the current directory are copied into the bundle directory (/cnab/app) in the invocation image. This will include any contributions from the mixin executables. Finally, an entry point that conforms to the CNAB specification is added to the image. | |
| Porter starts the [Dockerfile](/bundle/custom-dockerfile) by using a base image. You can customize the base image by specifying a Dockerfile template in the porter.yaml. By default, Porter only targets a single os/architecture(linux/amd64) for the bundle installer. If you want to use other platform, feel free to change the platform flag in the generated Dockerfile template. Next, a set of CA certificates is added. Then, contents of the current directory are copied into the bundle directory (/cnab/app) in the bundle installer. This will include any contributions from the mixin executables. Finally, an entry point that conforms to the CNAB specification is added to the image. |
| In the end, the result is a single invocation image with the necessary pieces: the porter-runtime, selected mixins and any relevant configuration files, scripts, charts or manifests. That invocation image can then be executed by any tool that supports the CNAB spec, while still taking advantage of the Porter capabilities. |
There was a problem hiding this comment.
| In the end, the result is a single invocation image with the necessary pieces: the porter-runtime, selected mixins and any relevant configuration files, scripts, charts or manifests. That invocation image can then be executed by any tool that supports the CNAB spec, while still taking advantage of the Porter capabilities. | |
| In the end, the result is a single bundle installer with the necessary pieces: the porter-runtime, selected mixins and any relevant configuration files, scripts, charts or manifests. That bundle installer can then be executed by any tool that supports the CNAB spec, while still taking advantage of the Porter capabilities. |
| description: Detailed look at how Porter does its magic 🎩✨ | ||
| --- | ||
|
|
||
| Porter is an implementation of the [Cloud Native Application Bundle](https://cnab.io/) specification and creates installers, known as bundles, that understand how to install not only your application but its infrastructure and configuration. A bundle helps you package up the logic for installing your application so that you can hand it off to another team, a customer, or just a co-worker who doesn’t know all the ins and outs of your application and provide them a consistent installation experience that doesn’t require them to know what tools you use to deploy or how the sausage is made. |
There was a problem hiding this comment.
Reading this sentence makes me really not like the s/invocation images/bundle installers/ I just did - if we can come up with a better name I'm down tho
| The Porter client is extensible and anyone can write a plugin to integrate with | ||
| Porter. Plugins extend the Porter client, reimplementing Porter's default | ||
| functionality. |
There was a problem hiding this comment.
| The Porter client is extensible and anyone can write a plugin to integrate with | |
| Porter. Plugins extend the Porter client, reimplementing Porter's default | |
| functionality. | |
| Plugins extend the Porter client, reimplementing Porter's default functionality. The Porter client is extensible and anyone can write a plugin to integrate with Porter. |
There was a problem hiding this comment.
I renamed this and forgot to delete this as it was moved to a new directory to be easily identified using the Hugo template.
|
|
||
| ## Getting Porter |
There was a problem hiding this comment.
| ## Getting Porter |
Having Porter should be a prereq
|
Yeah, my first pass was to provide the ToC with some inspiration from other projects. The content felt scattered TBH. I think we can collapse Introduction, QuickStart, and Getting Started under a Getting Started header. Again, I have not edited any of the actual markdown files. That will be a phase II effort. Let's focus on a ToC structure for the contents and identify areas where we will need to fill in the blanks. Give me some time to compose a new ToC to present here in the comments. |
|
Sounds good, thanks! |
I'm thinking this as the top level ToC :
|
| --- | ||
|
|
||
| Let's walk through how to create and customize your very own Porter bundle. | ||
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. |
There was a problem hiding this comment.
I'd add "runtime-environment" or equivalent to the list of what a bundle includes.
|
|
||
| Let's walk through how to create and customize your very own Porter bundle. | ||
| A bundle includes both the tools and the scripts or logic necessary to automate the deployment. | ||
| When writing a bundle, it is best if you have already figured out the commands necessary to perform the deployment first, and then use Porter to package that into a bundle. |
There was a problem hiding this comment.
Consider "workflow" over "commands".
| [Mixins] are adapters that makes it easier to work with existing tools within a bundle. | ||
| You can use the [porter mixins search] command to find existing mixins to use in your bundle. | ||
| A mixin handles installing any required tools for you, and provides an optimized experience for working with that tool in a bundle. | ||
| If you are working with the same tool often, eventually you will want to [create a custom mixin] so that you can write installation logic, error handling, common commands a single time and reuse them across your bundles. |
There was a problem hiding this comment.
I like the term "opinionated best practices" when it comes to describing mixins. The Terraform mixins logic to pull in modules deps for air gap use cases is a great example. Often folks don't think about air gap when working without a mixin.
Eventually, a "mixins vs plugins" section would be helpful. I often find myself having to explain the how they are different. I'm wondering if "extensions" might be a more pragmatic name for "mixins"
| ```yaml | ||
| mixins: | ||
| - exec | ||
| - terraform |
There was a problem hiding this comment.
It would be nice to show the clientVersion option under the terraform mixin. I find this connects the dots with experienced terraform users.
- terraform:
clientVersion: 1.5.1
|
|
||
| ### Use a Custom Dockerfile | ||
|
|
||
| When you are just getting started, it may be easier to start small and use a [custom Dockerfile] instead of creating your own mixins. |
There was a problem hiding this comment.
Perhaps a note reminding them to keep in mind pulling in all dependencies when working with a custom dockerfile? Bundles should not have to reach out to the internet when being executed.
| export VERSION="v1.0.14" | ||
| curl -L https://cdn.porter.sh/$VERSION/install-linux.sh | bash |
There was a problem hiding this comment.
Will we lose details for how to install an older version with the proposed change?
|
Let's discuss this in our next community call this week. I think there's two items for docs, the first being the restructuring of the content, and second is actually updating the docs themselves. I'm seeing a lot of updates to content of the docs, but those have always existed. I've made no changes to the markdown of the docs other than my formatter extension probably cleaned up some formatting. If we can agree on the content restructuring with a new ToC let's get that merged. We can then come back and focus on each section and edit the docs as appropriate. |
|
From today's community discussion, we were okay with approving this to set the TOC and relay the content back to unresolved issues? |
Let me go ahead an create issues for the comments. |
phillipgibson
force-pushed
the
main
branch
2 times, most recently
from
cae4131
to
8c6edf7
Compare
as per getporter#2790 Signed-off-by: sbshah97 <sbs.191197@gmail.com>
Update: Made changes to create bundle documentation as per #2790 Signed-off-by: sbshah97 <sbs.191197@gmail.com>
What does this change
This is the first of many docs changes to fix and align the Hugo template to logical file paths as well as provide a more user-friendly toc for users to onboard and use Porter.
What issue does it fix
Notes for the reviewer
This is the start of a series of doc updates.
Checklist
Reviewer Checklist