From d913e9ba821ae4c8bb60ef2c98a559f62cd399d0 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 7 Nov 2023 14:00:41 -0500 Subject: [PATCH] Add GH Pages infrastructure Start to migrate from README.md to the Pages infrastructure for nicer looking and more organized docs. --- .github/workflows/docs.yml | 43 ++++++++ README.md | 127 +++--------------------- docs/Gemfile | 14 +++ docs/_config.yml | 58 +++++++++++ docs/_sass/color_schemes/coreos.scss | 1 + cloud-agents.md => docs/cloud-agents.md | 4 + coreos.md => docs/coreos.md | 4 + docs/index.md | 118 ++++++++++++++++++++++ install.md => docs/install.md | 8 +- 9 files changed, 264 insertions(+), 113 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Gemfile create mode 100644 docs/_config.yml create mode 100644 docs/_sass/color_schemes/coreos.scss rename cloud-agents.md => docs/cloud-agents.md (98%) rename coreos.md => docs/coreos.md (95%) create mode 100644 docs/index.md rename install.md => docs/install.md (97%) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..5141b50 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,43 @@ +name: Docs + +on: + push: + branches: ["main"] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./docs + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/README.md b/README.md index 3d1025e..6f2f677 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,21 @@ -# Goals +# centos-boot -This project's toplevel goal is to create base *bootable* container images -from Fedora ELN and CentOS Stream packages. +Create and maintain base *bootable* container images from Fedora ELN and +CentOS Stream packages. -## Status +The longer term vision of this project is that the build infrastructure +(and possibly some of the container definitions) move into the respective +upstream operating systems. For now, this project acts as a more central +point for this across these distributions. -This is an in-development project not intended for production use yet. +## Motivation -## Trying it out +The original Docker container model of using "layers" to model +applications has been extremely successful. This project +aims to apply the same technique for bootable host systems - using +standard OCI/Docker containers as a transport and delivery format +for base operating system updates. -See [install.md](./install.md). +## More information -## Differences from Fedora CoreOS - -Fedora CoreOS today is not small; there are multiple reasons for this, but -primarily because it was created in a pre-bootable-container time. Not everyone -wants e.g. moby-engine. - -But going beyond size, the images produced by this project will focus -on a container-native flow. We will ship a (container) image that does not -include Ignition for example. - -## Differences from RHEL CoreOS - -We sometimes say that RHEL CoreOS [has FCOS as an upstream][1] but this is only -kind of true; RHEL CoreOS includes a subset of FCOS content, and is lifecycled -with OCP. - -An explicit goal of this project is to produce bootable container images -that can be used as *base images* for RHEL CoreOS; for more on this, see e.g. - - -## Differences from RHEL for Edge - -It is an explicit goal that CentOS boot also becomes a "base input" to RHEL for Edge. - -## What does CentOS boot means - -From [Wikipedia](https://en.wikipedia.org/wiki/Bamboo_Forest_(Kyoto,_Japan)): - -> Bamboo Forest, Arashiyama Bamboo Grove or CentOS boot Bamboo Forest, is a natural -> forest of bamboo in Arashiyama, Kyoto, Japan - -[1]: https://github.com/openshift/os/blob/master/docs/faq.md#q-what-is-coreos - -## Demonstration base images for Project CentOS boot - -These images are technology demonstrators, not for production use. The -intention is that these images are generated by the OS vendor or -distribution. -Or, you can fork this repository and generate your own via -`rpm-ostree compose image`. - -## Operating system sources - -At the moment these demonstration builds use Fedora ELN and CentOS Stream 9. - -## Tiers - -### Tier 0 - -This is the basic tier; it has effectively just: - -- kernel systemd selinux-policy-targeted bootc - -You are generally going to need to generate derived images from this; installing -it on its own will boot to a system with no automatic networking support, no SSH, -and no default passwords etc. - -### Tier 1 - -This is larger system. - -- NetworkManager, chrony -- rpm-ostree (to install packages and in case it's useful "day 2") -- openssh-server - -At the current time, it does not include Ignition or cloud-init; so you will -still need to derive from it in order to inject a mechanism to log in in many -cases. However, it will work to install it using e.g. Anaconda and set up -users and passwords that way. - -## Image matrix (Fedora) - -- `quay.io/centos-boot/fedora-tier-1:eln` - -### More about image sources - -The current manifest definitions [tier-0](tier-0) and [tier-1](tier-1) were -forked from Fedora CoreOS, but significantly cut down. - -The existing content set is obviously subject to change and debate. - -## Building - -Here's an example command: - -```shell -sudo rpm-ostree compose image --authfile ~/.config/containers/myquay.json --cachedir=cache -i --format=ociarchive centos-tier-0-stream9.yaml centos-tier-0-stream9.ociarchive -``` - -In some situations, copying to a local `.ociarchive` file is convenient. You -can also push to a registry with `--format=registry`. - -More information at - -## Badges - -| Badge | Description | Service | -| ----------------------- | -------------------- | ------------ | -| [![Renovate][1]][2] | Dependencies | Renovate | -| [![Pre-commit][3]][4] | Static quality gates | pre-commit | - -[1]: https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovate -[2]: https://renovatebot.com -[3]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit -[4]: https://pre-commit.com/ +See the [project documentation](https://centos.github.io/centos-boot/). diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..1ffd2a0 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,14 @@ +# Bundler setup for jekyll to be deployed on github pages. + +source "https://rubygems.org" + +# Note that we're using the github-pages gem to mimic the GitHub pages +# automated setup. That installs jekyll, a default set of jekyll +# plugins, and a modified jekyll configuration. +group :jekyll_plugins do + gem "github-pages" + gem "jekyll-remote-theme" +end + +# Prefer the GitHub flavored markdown version of kramdown. +gem "kramdown-parser-gfm" diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..24b2189 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,58 @@ +title: containers/bootc +description: bootc documentation +baseurl: "/centos-boot" +url: "https://centos.github.io" +# Comment above and use below for local development +# url: "http://localhost:4000" +permalink: /:title/ +markdown: kramdown +kramdown: + typographic_symbols: + ndash: "--" + mdash: "---" + +# Exclude the README and the bundler files that would normally be +# ignored by default. +exclude: + - README.md + - Gemfile + - Gemfile.lock + - prep-docs.sh + - vendor/ + +# These are copies of the apidoc/html and man/html directories. Run +# prep-docs.sh before jekyll to put it in place. +include: [reference, man] + +remote_theme: just-the-docs/just-the-docs@v0.4.1 +plugins: + - jekyll-remote-theme + +color_scheme: coreos + +# Aux links for the upper right navigation +aux_links: + "bootc on GitHub": + - "https://github.com/containers/bootc" + +footer_content: "Copyright © Red Hat, Inc. and others." + +# Footer last edited timestamp +last_edit_timestamp: true +last_edit_time_format: "%b %e %Y at %I:%M %p" + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true +gh_edit_link_text: "Edit this page on GitHub" +gh_edit_repository: "https://github.com/containers/bootc" +gh_edit_branch: "main" +gh_edit_source: docs +gh_edit_view_mode: "tree" + +compress_html: + clippings: all + comments: all + endings: all + startings: [] + blanklines: false + profile: false diff --git a/docs/_sass/color_schemes/coreos.scss b/docs/_sass/color_schemes/coreos.scss new file mode 100644 index 0000000..a4554be --- /dev/null +++ b/docs/_sass/color_schemes/coreos.scss @@ -0,0 +1 @@ +$link-color: #53a3da; diff --git a/cloud-agents.md b/docs/cloud-agents.md similarity index 98% rename from cloud-agents.md rename to docs/cloud-agents.md index 2d093dd..afa0a10 100644 --- a/cloud-agents.md +++ b/docs/cloud-agents.md @@ -1,5 +1,9 @@ # Project CentOS boot tier-1 and cloud agents +--- +nav_order: 2 +--- + The tier-0 and tier-1 images today do not contain any special hypervisor-specific agents. The following specifically are not included for example: diff --git a/coreos.md b/docs/coreos.md similarity index 95% rename from coreos.md rename to docs/coreos.md index b780b89..1044f82 100644 --- a/coreos.md +++ b/docs/coreos.md @@ -1,5 +1,9 @@ # Relationship with CoreOS +--- +nav_order: 5 +--- + The CoreOS Container Linux project was very successful, spawning multiple projects and derivatives that continue to see widespread use today. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3d1025e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,118 @@ +# Goals + +This project's toplevel goal is to create base *bootable* container images +from Fedora ELN and CentOS Stream packages. + +## Status + +This is an in-development project not intended for production use yet. + +## Trying it out + +See [install.md](./install.md). + +## Differences from Fedora CoreOS + +Fedora CoreOS today is not small; there are multiple reasons for this, but +primarily because it was created in a pre-bootable-container time. Not everyone +wants e.g. moby-engine. + +But going beyond size, the images produced by this project will focus +on a container-native flow. We will ship a (container) image that does not +include Ignition for example. + +## Differences from RHEL CoreOS + +We sometimes say that RHEL CoreOS [has FCOS as an upstream][1] but this is only +kind of true; RHEL CoreOS includes a subset of FCOS content, and is lifecycled +with OCP. + +An explicit goal of this project is to produce bootable container images +that can be used as *base images* for RHEL CoreOS; for more on this, see e.g. + + +## Differences from RHEL for Edge + +It is an explicit goal that CentOS boot also becomes a "base input" to RHEL for Edge. + +## What does CentOS boot means + +From [Wikipedia](https://en.wikipedia.org/wiki/Bamboo_Forest_(Kyoto,_Japan)): + +> Bamboo Forest, Arashiyama Bamboo Grove or CentOS boot Bamboo Forest, is a natural +> forest of bamboo in Arashiyama, Kyoto, Japan + +[1]: https://github.com/openshift/os/blob/master/docs/faq.md#q-what-is-coreos + +## Demonstration base images for Project CentOS boot + +These images are technology demonstrators, not for production use. The +intention is that these images are generated by the OS vendor or +distribution. +Or, you can fork this repository and generate your own via +`rpm-ostree compose image`. + +## Operating system sources + +At the moment these demonstration builds use Fedora ELN and CentOS Stream 9. + +## Tiers + +### Tier 0 + +This is the basic tier; it has effectively just: + +- kernel systemd selinux-policy-targeted bootc + +You are generally going to need to generate derived images from this; installing +it on its own will boot to a system with no automatic networking support, no SSH, +and no default passwords etc. + +### Tier 1 + +This is larger system. + +- NetworkManager, chrony +- rpm-ostree (to install packages and in case it's useful "day 2") +- openssh-server + +At the current time, it does not include Ignition or cloud-init; so you will +still need to derive from it in order to inject a mechanism to log in in many +cases. However, it will work to install it using e.g. Anaconda and set up +users and passwords that way. + +## Image matrix (Fedora) + +- `quay.io/centos-boot/fedora-tier-1:eln` + +### More about image sources + +The current manifest definitions [tier-0](tier-0) and [tier-1](tier-1) were +forked from Fedora CoreOS, but significantly cut down. + +The existing content set is obviously subject to change and debate. + +## Building + +Here's an example command: + +```shell +sudo rpm-ostree compose image --authfile ~/.config/containers/myquay.json --cachedir=cache -i --format=ociarchive centos-tier-0-stream9.yaml centos-tier-0-stream9.ociarchive +``` + +In some situations, copying to a local `.ociarchive` file is convenient. You +can also push to a registry with `--format=registry`. + +More information at + +## Badges + +| Badge | Description | Service | +| ----------------------- | -------------------- | ------------ | +| [![Renovate][1]][2] | Dependencies | Renovate | +| [![Pre-commit][3]][4] | Static quality gates | pre-commit | + +[1]: https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovate +[2]: https://renovatebot.com +[3]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit +[4]: https://pre-commit.com/ diff --git a/install.md b/docs/install.md similarity index 97% rename from install.md rename to docs/install.md index 43da808..57b2014 100644 --- a/install.md +++ b/docs/install.md @@ -1,5 +1,10 @@ -# Trying out Project CentOS boot development builds +# Trying out development builds +--- +nav_order: 2 +--- + + ## Rebasing from Fedora CoreOS