Let's create a PipeCD hands-on tutorial for beginners

[t-kikuc]

What I want

• A hands-on introduction for beginners.
  • It will include running PipeCD locally and deploying applications.

Why I want

• To make it easier to start learning/running PipeCD in order to increase the number of PipeCD users.
  • i.e. To reduce the abandonment rate of those who're interested in PipeCD until they start using PipeCD.
• The background: it is difficult for beginners to start PipeCD because:
  • the installation is not easy (they need a Control Plane, a Piped, and configs), so they tend to fail and exit
  • the official doc is not intended for beginners, so they get confused about where to read

Notes

• Intended readers

  • Intended for those who want to learn PipeCD with hands-on experience.
  • Not intended for those who want to start developing PipeCD.

• Table of contents (To Be Updated. If you have any requests, please share us!)

  • PipeCD Overview (what's & why PipeCD, architecture overview)
  • Prerequisites
  • Quickstart (optional) (I'm wondering if we need it here) Not included
  • Local Run
    • Control Plane: docker-compose
    • Piped: run a container
    • Let's deploy example applications
  • Other Useful Features (optional)

• How to publish it:

  • Create a new repository under the pipe-cd org like 'pipecd-tutorial'
    • To keep this repo simple and to make it easier to edit the tutorial
  • Use Hugo and Docsy as the site template (the same as this repo)
  • [TBD] the domain name, host, etc.
    • cf. https://github.com/pipe-cd/pipecd/blob/master/.github/workflows/publish_site.yaml

[t-kikuc]

[WIP] I'm building it like this:
I hope to publish it this month🚀 .

[t-kikuc]

Quickstart (optional) (I'm wondering if we need it here)

I've decided not to include the QuickStart because:

• Those who can try QuickStart probably have already done that without this tutorial. The target users of this tutorial are different.
• If QuickStart is contained in this tutorial, users need to setup for QuickStart in addition to for local running.

[khanhtc1202]

@t-kikuc

I agree with not adding the quickstart instruction to this docs.

However, I am concerned about how to use PipeCD locally (to dev or test). The image above shows that we recommend using docker-compose as a locally pipecd environment, but I think we should prefer KIND over docker-compose. One of my strong points is that I want the devs/test environment to be the same as the prod environment, which reduces the risk of config missing or such. Of course, we can also have instructions for using the PipeCD control plane with docker-compose, but it should not be the main one. WDYT?

[t-kikuc]

[FYI] The new image of architecture of local running (essentially not changed from the top one):
docker-compose might change to KIND.

[t-kikuc]

@khanhtc1202

I think we should prefer KIND over docker-compose.

I also think it's better to use KIND here although I think we should focus on easier setup, not on dev/test in the tutorial.

I will try installing by KIND later. If it's easier, I'll change to KIND.

[khanhtc1202]

@t-kikuc How about to keep both, but prefer Kind as first option. I mean we are freed from making this tutorial as quick/short as possible but focus on user-friendly point. So having both (or even more like k3s, lima, etc) is a good point.

[t-kikuc]

@khanhtc1202

How about to keep both, but prefer Kind as first option

That sounds good.
Since installing by docker-compose requires only one command without configuring (see the image),
an additional option of installing byKind would not be noisy for users.

[t-kikuc]

@khanhtc1202
I'd like to add the simple command to install in Kind after publishing
because it takes a long time to create and verify it.

[khanhtc1202]

Sure, and also it's a bit hard to image how it look like for now so it would be great if you can push WIP somewhere 👀

[t-kikuc]

How to publish it:

I want to publish it as GitHub markdowns and quit publishing as a website because:

• Preparing and maintaining a website require a lot of works (e.g. styles, manifests, GitHub Actions, Dockerfile, etc.).
• However, we don't need Hugo's useful features here because the size of tutorial is not large. (e.g. search, outline, etc.)

If many users want view as a website after publishing, then we'll reconsider it. That's enough.

cf. the image will be as below.

[t-kikuc]

The reasons why I won't publish on PipeCD Docs:

• For i18n. I want to publish the Japanese version.
• For keeping the main repo simple.
• For developing this tutorial easier.
  • the main repo requires heavier reviews.

[t-kikuc]

Finally, We published !!!!

https://github.com/pipe-cd/tutorial

[khanhtc1202]

Great work, thank you 🙌

[t-kikuc]

Piped: run a container

I chose running as a single binary because it's troublesome to pass a lot of auth to a container.
(e.g. kubeconfig, AWS auth, GitHub ssh key)