It would be great to have following requirements of Tinkerbell included in the documentation, perhaps new section called "Requirements".

• OS for server:
  • As far as I know, currently Ubuntu 16.04/20.04 and some CentOS versions are supported by setup.sh script
• CPU, RAM, disk:
  • I test on 2 vCPUs and 4 GB of RAM and that seems to be sufficient
  • 20 GB disk seems to be sufficient (including OS)
• CPU architecture of workers and Tinkerbell server:
  • e.g. does it work on ARM?
• Network:
  • As far as I know, L2 network is required with ability to run your own DHCP server
• Workers:
  • workers must be able to boot from network using iPXE

Our repositories should be the example from which adjacent, competing, projects look for inspiration.

Each repository should not look entirely different from other repositories in the ecosystem, having a different layout, a different testing model, or a different logging model, for example, without reason or recommendation from the subject matter experts from the community.

We should share our improvements with each ecosystem while seeking and respecting the feedback of these communities.

Whether or not strict guidelines have been provided for the project type, our repositories should ensure that the same components are offered across the board. How these components are provided may vary, based on the conventions of the project type. GitHub provides general guidance on this which they have integrated into their user experience.

Expected Behaviour

We believe this repository is Maintained and therefore needs the following files updated:

• Flagged Public
• The Maintained badge #139
• The Maintained Statement in the README.md #139
• Getting Started Tutorial
• README.md
• LICENSE
• CI/CD
• OWNERS.md #141
• Developer Certificate of Origin
• At least two maintainers
• A Manifest File, if relevant
• Code of Conduct #138
• How to Contribute #107
• SUPPORT.md #140
• RELEASE.md

If you feel the repository should be experimental or end of life or that you'll need assistance to update these files, please let us know by filing an issue with https://github.com/packethost/standards.

Current Behaviour

n/a

Possible Solution

n/a

Context

Packet maintains a number of public repositories that help customers to run various workloads on Packet. These repositories are in various states of completeness and quality, and being public, developers often find them and start using them. This creates problems:

• Developers using low-quality repositories may infer that Packet generally provides a low quality experience.
• Many of our repositories are put online with no formal communication with, or training for, customer success. This leads to a below average support experience when things do go wrong.
• We spend a huge amount of time supporting users through various channels when with better upfront planning, documentation and testing much of this support work could be eliminated.

To that end, we propose three tiers of repositories: Private, Experimental, and Maintained.

As a resource and example of a maintained repository, we've created https://github.com/packethost/standards. This is also where you can file any requests for assistance or modification of scope.

Your Environment

• https://github.com/tinkerbell/tinkerbell.org

Thanks @ronggur
Tinkerbell_Lockup_white_horz.svg.zip

Issue unrelated to the web site, to test correct operations of Slack integration. To be closed after it works.

We should aim to reduce a user's "time to dopamine" by creating an unboxing experience that allows users to get Tinkerbell up and running and doing something useful or interesting, quickly. This is split into three sections:

Setup Experience

The docs should cover how to set up the provisioner in the following situations:

• 1. On Packet, using Terraform
• 2. Local with VMs (Vagrant/VirtualBox etc) (Ubuntu 18.04 provisioner)

Examples

• Example 1: Install Ubuntu 18.04 on worker and add ssh key

Documentation

The documentation should introduce terminology inline so that users don't need to constantly click away breaking their flow.

Let's please have someone from outside of the core team (like Devrel) try out the docs before we push them out to make sure they are understandable to people without intimate knowledge of Tinkerbell.

As the unboxing experience can be degraded by out of date code examples, let's also set up CI to test each of the workflows, including a nightly build in case of Packet API changes.

To come back to:

• 2. Local Ubuntu 18.04 & 20.04 , CentOS 7 & 8 (pre-amble including assumptions i.e. two machines in a flat layer 2 environment)
• RPI4
• Example 2: Spin up a k8s cluster on the worker(s) <-- We can reference Adam Otto's work for this
• Example 3: Show how a user can bring their own ISO
• Example 4: Flatcar Linux ← #28

https://tinkerbell.org/setup currently points to Packet specific documentation.

Let's instead update this page to the latest docs.

This looks like a good start: tinkerbell/tink#49

I'd love to embed these videos if they are up to date: tinkerbell/tink#62 (If we do this let's make a reminder to update them whenever the instructions change)

From @iaguis on the community slack.

"I'm following the setup tutorial on tinkerbell.org on Packet and got to the Hardware data section. It says: "Create a file containing the hardware data (say data.json)", but gives no information on what this "hardware data" is, I think it should have some information about that, maybe pointing to https://tinkerbell.org/cli-reference/hardware/ can be a first step."

@invidian kindly suggests the following:

{"id": "fd73de05-dc53-495d-90a1-4ab0aae73339", "arch": "x86_64", "allow_pxe": true, "ip_addresses": [{"address": "192.168.50.11", "gateway": "192.168.50.2", "netmask": "255.255.255.0", "address_family": 4}], "network_ports": [{"data": {"mac": "08:00:27:ea:b7:90"}, "name": "eth0", "type": "data"}], "allow_workflow": true}

The UUID you need to generate yourself
The mac address will be used for iPXE and address will be served by DHCP

"Get Started on Github" -> "Get Started"
Links to Setup: https://deploy-preview-27--festive-goldwasser-489842.netlify.app/setup/

Community Slack

Tinkerbell leverages Packet's community Slack channel. Please join and look for the #tinkerbell channel to get involved!
[Join Packet Community on Slack]

Mockup:

Could we utilize this secondary nav to have a page with URL?

And, after this page has URL, we shall point the Landing's main nav "Slack Channel" to it also (instead of to https://slack.packet.net/)

Currently the local setup section of the docs references cd /vagrant && source .env && cd deploy which according to the setup.sh should be cd /vagrant && source .envrc && cd deploy

tinkerbell.org has a favicon. docs.tinkerbell.org does not have a favicon.

I would like docs.tinkerbell.org to have the same favicon as tinkerbell.org.

Expected Behaviour

See above

Current Behaviour

See above

Possible Solution

See above

Steps to Reproduce (for bugs)

1. Open tinkerbell.org in a browser
2. Open docs.tinkerbell.org in a browser

Context

See above

Your Environment

n/a

When potential users are evaluating Tinkerbell they will naturally want to know how it is better or different than current solutions in the market. This is evidenced by the recent commentary on Reddit:
https://www.reddit.com/r/selfhosted/comments/gdyy9p/open_sourcing_tinkerbell_for_automated_baremetal/

We can build up the FAQ as we go but a good base line of questions from the link above are:

• How does Tinkerbell compare to DigitalRebar?
• How does Tinkerbell compare to Foreman discovery?
• How does Tinkerbell compare to Canonical MAAS?

Proposed first list of questions:

1. Does Tinkerbell work outside of Packet's hosting service, and has this been tested?

Yes, it will work outside of Packet. Our default setup script should work on any install of Ubuntu and CentOS.

2. Does using Tinkerbell rely on having a Packet account?

No

3. Can Tinkerbell be used to install OSes without Internet access (where both the Provider and Worker hosts are in an isolated network)?

Yes

4. What operating systems is Tinkerbell able to install?

Any! Out of the box, we are endeavoring to provide installation workflows for deb and rpm-based systems, but it can be used for anything (as it includes a generic workflow engine).

5. Can Tinkerbell install operating systems using their original, unmodified ISO images?

Yes

6. Which server makes and models is Tinkerbell able to install operating systems on?

Currently works on any system with IPMI, with special support for Dells (racadm). Host-side, our installation has support for a lot of NICs, e.g. Broadcom, Intel, Netronome, Mellanox, and a few others out of the box.

7. Does Tinkerbell have code to support (installing OSes on) specific server makes/models, or does it use standard interfaces only?

Our out of the box experience should allow you to install Ubuntu and CentOS easily.

8. Is Tinkerbell able to operate remote server power settings (power on; power off)? How about resetting?

Yes, via the pbnj microservice (https://github.com/tinkerbell/pbnj)

9. When using Tinkerbell to install an operating system, are there any operations that need manual intervention?

Nothing that we have created needs manual intervention

10. Does Tinkerbell use each operating system's native network installer program, or does it install using a different method?

It depends on the operating system, the installation environment supports non-NM and NM for rpm-based systems, and the standard deb-based network interfaces.

tinkerbell organization on GitHub directs to https://www.tinkerbell.org which gives certificate error.

There have been a few recent changes to hardware data. With the merging and closing of tinkerbell/tink@850584d and tinkerbell/tink#199.

I can take a look at https://tinkerbell.org/hardware-data/ and update it including some of those recent changes.

It seems to have raised at least one question so far (https://packetcommunity.slack.com/archives/CPPU9TWSV/p1595866912461600)

We need a contributors' page for Tinkerbell.org

We need the contributors' name, GitHub handle, Twitter handle, and avatars.

https://docs.google.com/spreadsheets/d/1pLlyh5A3ZIhp8ePAxWY8CTvhUSm5rBXlGQ7pneoG50I/edit?usp=sharing

@felixwidjaja has created this mockup

@kdeng3849 has already started this in tinkerbell/tink#64

Expected Behaviour

We moved our docs to docs.tinkerbell.org and the tinkerbell.org/docs need to be removed.

Current Behaviour

Possible Solution

Steps to Reproduce (for bugs)

Context

Your Environment

• Operating System and version (e.g. Linux, Windows, MacOS):

• How are you running Tinkerbell? Using Vagrant & VirtualBox, Vagrant & Libvirt, on Packet using Terraform, or give details:

• Link to your project or a code example to reproduce issue:

from slack.packet.net to slack.packet.com

Linked Issue: tinkerbell/tink#116

Problem:
Currently, when a workflow is done and the user reboots, workers PXE-boot again to OSIE unless you manually set boot to disk.

Solution:
With Issue tinkerbell/smee#35 a logic was implemented to have worker PXE boot only when there is an Active workflow created for the given worker. Worker will not PXE boot if there is ont active workflow or existing workflows defined for given worker are either completed or Failed.

Case-1:
On the first boot, worker is brought up with light weight Alpine OS and then subsequently workflows are executed onto the worker. If as a part of the workflow, such steps are executed which installs new OS on the worker and completes successfully, then the boot request (after reboot) would be handled by newly installed OS. Thus, the worker may request PXE boot.

Case-2:
If as a part of the workflow, OS is not installed then worker after reboot will request PXE-boot from the tink-server. With above mentioned issue boots#35, tink-server now need an active workflow defined to accept the request of the worker.
With above 2 cases, this issue (tink#116) is handled.

Hello!

We believe this repository is Experimental and therefore needs the following files updated:

• The Experimental badge #139
• The Experimental Statement in the README.md #139
• Getting Started Tutorial
• README.md
• LICENSE
• CI/CD
• OWNERS.md #141
• Developer Certificate of Origin
• At least one maintainer

If you feel the repository should be maintained or end of life or that you'll need assistance to create these files, please let us know by filing an issue with https://github.com/packethost/standards.

Packet maintains a number of public repositories that help customers to run various workloads on Packet. These repositories are in various states of completeness and quality, and being public, developers often find them and start using them. This creates problems:

• Developers using low-quality repositories may infer that Packet generally provides a low quality experience.
• Many of our repositories are put online with no formal communication with, or training for, customer success. This leads to a below average support experience when things do go wrong.
• We spend a huge amount of time supporting users through various channels when with better upfront planning, documentation and testing much of this support work could be eliminated.

To that end, we propose three tiers of repositories: Private, Experimental, and Maintained.

As a resource and example of a maintained repository, we've created https://github.com/packethost/standards. This is also where you can file any requests for assistance or modification of scope.

The Goal

Our repositories should be the example from which adjacent, competing, projects look for inspiration.

Each repository should not look entirely different from other repositories in the ecosystem, having a different layout, a different testing model, or a different logging model, for example, without reason or recommendation from the subject matter experts from the community.

We should share our improvements with each ecosystem while seeking and respecting the feedback of these communities.

Whether or not strict guidelines have been provided for the project type, our repositories should ensure that the same components are offered across the board. How these components are provided may vary, based on the conventions of the project type. GitHub provides general guidance on this which they have integrated into their user experience.

If you use the newest version of Hugo the website does not work.

#90

Tiny issue with incomplete command in the example on https://tinkerbell.org/docs/cli/template/

Current docs

Examples

template create --name hello-world < ./hello-world.yml
>
Created Template:  b8dbcf07-39dd-4018-903e-1748ecbd1986

in https://github.com/tinkerbell/tinkerbell.org/blob/master/content/docs/cli/template.md.

Should be

Examples

tink template create --name hello-world < ./hello-world.yml
>
Created Template:  b8dbcf07-39dd-4018-903e-1748ecbd1986

Expected Behaviour

IMHO this is a P2 because I feel blocked from writing documentation for contributors until we don't have a place for it.

As a potential contributor, I want to be able to get my own documentation, because maybe I am a user as well for Tinkerbell but I have different needs.

Recently worked with bird, and I know, the site has its style that comes directly from the 80s but I like how clearly it brings me to my journey as a user or as a contributor.

This is an example of this issue that I would like to see documented in the "contributor" section tinkerbell/tink#177 . A lot of the documentation as I wrote there needs to be in the code itself, but from the website, we should point the contributor in the right direction explaining more high level what the testing framework is designed for and what it provides.

@DailyAlice what do you think?

It would be nice to have a note somewhere, that in order to debug the workflow, root user with no password can be used for loggin in into serial console

hi @geriadam please change to Equinix Metal
Thanks.

The next version of the web site will be done with Hugo and Netlify - track that progress here.

Building out the reference docs with some common information and formatting as well as examples for every command. Also serves as a useful template if/when the cli gets new functionality down the line.

We would like to know how much traffic we're getting and which pages are popular. Please add GA to tinkerbell.org and ping me for the tracking code.

https://github.com/tinkerbell/tinkerbell.org/blob/master/content/setup/packet/provisioner.md

The _setup.sh_ script will:
    - configure the network
    - download necessary files
    - setup the certificates
    - setup a Docker registry
    - start tinkerbell components

Looks like:

From notes from Nathan:

Build a lightweight portal that would say “here’s your hardware that’s in this facility, here are your templates, your workflows.” Also allow users to create new templates and workflows.

Not a recreation of the multi tenant staff portal.

Extra notes:

1. Switch UI so Hardware shows a list and then you can edit, delete and upload within that page.
2. System status: List running containers
3. About page include running versions
4. Doesn't need to be branded like Tinkerbell, think more like Google Console.
5. Assuming PBNJ is running rebooting or kicking off a workflow through the UI
6. Inspect container registry to see which containers are available.

@jacobsmith928 will help.

Need revision about the major components quantity @mrmrcoleman
https://deploy-preview-27--festive-goldwasser-489842.netlify.app/

I saw some "Github" in homepage instead of "GitHub".
Please edit thanks.

We have not been able to build the Tinkerbell Hugo site locally. We need to be able to build locally to test and iterate, especially on docs. There are errors are listed below:

Building sites … WARN 2020/06/29 15:03:12 Page.URL is deprecated and will be removed in a future release. Use .Permalink or .RelPermalink. If what you want is the front matter URL value, use .Params.url
ERROR 2020/06/29 15:03:12 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:28:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/Users/thomcrowe/documents/packet/tinkerbell.org/layouts/partials/menu.html:99:23": execute of template failed: template: partials/menu.html:99:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/06/29 15:03:12 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:28:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/Users/thomcrowe/documents/packet/tinkerbell.org/layouts/partials/menu.html:99:23": execute of template failed: template: partials/menu.html:99:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/06/29 15:03:12 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:28:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/Users/thomcrowe/documents/packet/tinkerbell.org/layouts/partials/menu.html:99:23": execute of template failed: template: partials/menu.html:99:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/06/29 15:03:12 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:28:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/Users/thomcrowe/documents/packet/tinkerbell.org/layouts/partials/menu.html:99:23": execute of template failed: template: partials/menu.html:99:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
Built in 71 ms
Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:28:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/Users/thomcrowe/documents/packet/tinkerbell.org/layouts/partials/menu.html:99:23": execute of template failed: template: partials/menu.html:99:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden

@ronggur please edit based on Kyle's suggestion at here.
Thank you.

Documentation
GitHub
Slack Channel
Twitter

https://deploy-preview-27--festive-goldwasser-489842.netlify.app/

@ronggur

There was a request for docs surrounding iptables on a Worker post-Vagrant set up.

Need to follow-up with @Cbkhare, @gianarb, or @dan to get the details.

A request from @jacobsmith928

Adjust the capitalization on the website to match this:

• boots — DHCP & iPXE Server
• OSIE — In-Memory Environment
• tink — Provisioning & Workflow Engine
• hegel — Metadata Service

Related to tinkerbell/tink#91

Currently "Documentation" button on the main page redirects directly to https://tinkerbell.org/components/. Perhaps it would be nice to have some kind of overview page of what you can find in there, how to contribute etc.

Expected Behaviour

Code coloring in the docs and on the website should look something like:

Current Behaviour

But (in at least Firefox) with the "user prefers dark mode" option set it looks like:

Possible Solution

Might need to take a look at a few other browsers/dark mode options, as well as how our Hugo does colors

There seems to be a line break conflict somewhere between running prettier and deploying to staging/live environment where a line break in markdown isn't registered as a line break in live. It looks like prettier is removing the extra white space and taking away the break. Hugo appears to need that double spaces and a carriage return to display the break.

Below are two screenshots, one showing the code for the new docs landing page and the landing page in staging. The contributor line, for example, is mashed into one paragraph instead of displaying the line break.

As described in here.

https://tinkerbell.org/examples/hello-world/

1. @ronggur can you edit theme for <a> to be the underlined? Hover will change the color, or lose the underline.
2. While you at it, please edit the link to https://tinkerbell.org/setup/ because the current one is 404.

*Thanks to Alex Ellis for this.

Expected Behaviour

The instructions at https://tinkerbell.org/setup/packet-with-terraform/provisioner/ should work.

$ wget https://raw.githubusercontent.com/tinkerbell/tink/master/setup.sh && chmod +x setup.sh
$ ./setup.sh

Current Behaviour

root@tink-provisioner:~# ./setup.sh
INFO: starting tinkerbell stack setup
INFO: verifying prerequisites for ubuntu (18.04)
ERROR: Prerequisite command not installed: docker
ERROR: Prerequisite command not installed: docker-compose

Possible Solution

Run the following before wget'ing setup.sh.

$ apt update
$ apt install -y docker.io docker-compose

Rather than having these steps performed manually, they could be performed by Terraform, through a null_resource provisioner, or through cloud-init.

Steps to Reproduce (for bugs)

1. terraform init && terraform apply
2. ssh root@$(terraform output provisioner_dns_name)
3. wget https://raw.githubusercontent.com/tinkerbell/tink/master/setup.sh && chmod +x setup.sh
4. ./setup.sh

Context

Your Environment

• Operating System and version (e.g. Linux, Windows, MacOS):

• How are you running Tinkerbell? Using Vagrant & VirtualBox, Vagrant & Libvirt, on Packet using Terraform, or give details:

• Link to your project or a code example to reproduce issue:

hi @geriadam @ronggur please set the link in header & footer of Docs to https://docs.tinkerbell.org/
Thanks.

Now it looks pink.

Can you make it to #1d5086?

Active color glow is great already.

Please change the background to use the same dark blue @ronggur
https://deploy-preview-27--festive-goldwasser-489842.netlify.app/components/