Initial commit

.github/workflows/publish-docs.yml

@@ -0,0 +1,27 @@
+name: Build and publish docs
+on:
+  push:
+    branches:
+      - "main"
+  pull_request: {}
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: Build docs
+        run: CONTAINER_RUNTIME=docker make build_docs
+      - name: Check links in docs
+        run: CONTAINER_RUNTIME=docker make docs_check_links
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/crc

Containerfile

@@ -0,0 +1,11 @@
+FROM docker.io/antora/antora
+LABEL org.opencontainers.image.source="https://github.com/crc-org/crc"
+RUN yarn global add --ignore-optional --silent \
+    @antora/atlas-extension \
+    @antora/cli \
+    @antora/collector-extension \
+    @antora/lunr-extension \
+    @antora/pdf-extension \
+    @antora/site-generator \
+    asciidoctor-kroki
+RUN antora --version

Makefile

@@ -0,0 +1,20 @@
+SHELL := /bin/bash -o pipefail
+
+# Docs build related variables
+DOCS_BUILD_DIR ?= docs/build
+DOCS_BUILD_CONTAINER ?= quay.io/crcont/antora:latest
+DOCS_SERVE_CONTAINER ?= docker.io/httpd:alpine
+DOCS_TEST_CONTAINER ?= docker.io/wjdp/htmltest:latest
+DOCS_BUILD_TARGET ?= /docs/source/getting_started/master.adoc
+
+.PHONY: build_docs
+build_docs:
+	${CONTAINER_RUNTIME} run -v $(CURDIR):/antora$(SELINUX_VOLUME_LABEL) --rm $(DOCS_BUILD_CONTAINER) --stacktrace antora-playbook.yml
+
+.PHONY: docs_serve
+docs_serve: build_docs
+	${CONTAINER_RUNTIME} run -it -v $(CURDIR)/docs/build:/usr/local/apache2/htdocs/$(SELINUX_VOLUME_LABEL) --rm -p 8088:80/tcp $(DOCS_SERVE_CONTAINER)
+
+.PHONY: docs_check_links
+docs_check_links:
+	${CONTAINER_RUNTIME} run -v $(CURDIR):/test$(SELINUX_VOLUME_LABEL) --rm $(DOCS_TEST_CONTAINER) -c .htmltest.yml

OWNERS

@@ -0,0 +1,7 @@
+# See the OWNERS docs: https://git.k8s.io/community/contributors/guide/owners.md
+# This file just uses aliases defined in OWNERS_ALIASES.
+
+approvers:
+  - crc-approvers
+reviewers:
+  - doc-reviewers

README.md

@@ -1,2 +1,16 @@
-# docs
 CRC User documentation; Getting Started Guide
+=============================================
+
+
+## Prerequisites
+* A container engine, such as Podman or Docker.
+
+## Procedure
+
+* Build and serve the documentation:
+
+```shell
+$ make docs_serve
+```
+
+The documentation will be available locally at http://localhost:8088/.

antora.yml

@@ -0,0 +1,7 @@
+---
+name: getting_started
+title: Getting started with CRC
+version: ~ # Unversioned component version
+start_page: getting_started:introducing.adoc
+nav:
+  - modules/getting_started/nav.adoc

extensions/get-versions.js

@@ -0,0 +1,46 @@
+"use strict";
+const fs = require("fs");
+const child_process = require("child_process");
+module.exports.register = function () {
+  this.on("playbookBuilt", function ({ playbook }) {
+    // Get versions from Makefile
+    // Use utf8 encoding to have a string rather than a buffer in the output
+    const ocp_ver_full = child_process.execSync(
+      "grep '^OPENSHIFT_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'",
+      { encoding: "utf8" }
+    );
+    const ocp_ver = child_process.execSync(
+      "grep '^OPENSHIFT_VERSION' Makefile | cut -d' ' -f3 | cut -d'.' -f-2 | tr -d '\n'",
+      { encoding: "utf8" }
+    );
+    const prod_ver_full = child_process.execSync(
+      "grep '^CRC_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'",
+      { encoding: "utf8" }
+    );
+    const prod_ver = child_process.execSync(
+      "grep '^CRC_VERSION' Makefile | cut -d' ' -f3 | cut -d'.' -f-2 | tr -d '\n'",
+      { encoding: "utf8" }
+    );
+    const ushift_ver = child_process.execSync(
+      "grep '^MICROSHIFT_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'",
+      { encoding: "utf8" }
+    );
+
+    // Display versions
+    console.log("OpenShift patch version: " + ocp_ver_full);
+    console.log("OpenShift minor version: " + ocp_ver);
+    console.log("CRC patch version: " + prod_ver_full);
+    console.log("CRC minor version: " + prod_ver);
+    console.log("MicroShift version: " + ushift_ver);
+
+    // Set attributes values
+    Object.assign(playbook.asciidoc.attributes, {
+      "ocp-ver": ocp_ver,
+      "ocp-ver-full": ocp_ver_full,
+      "prod-ver": prod_ver,
+      "prod-ver-full": prod_ver_full,
+      "ushift-ver": ushift_ver,
+    });
+    this.updateVariables({ playbook });
+  });
+};

modules/getting_started/examples/snip_crc_preset_list.adoc

@@ -0,0 +1,3 @@
+`openshift`:: {ocp}
+`okd`:: {okd}
+`microshift`::  {ushift}

modules/getting_started/examples/snip_crc_preset_names.adoc

@@ -0,0 +1,8 @@
+.Preset names
+[%header,format=csv,cols="1,2"]
+|===
+Name, Preset
+`openshift`, {ocp}
+`okd`, {okd}
+`microshift`, {ushift}
+|===

modules/getting_started/examples/snip_crc_preset_platforms.adoc

@@ -0,0 +1,8 @@
+.Preset and architecture compatibility
+[%header,format=csv,cols="3,1,1,1"]
+|===
+Preset, AMD64, Intel 64, Apple silicon
+{ocp}, yes, yes,  yes
+{okd}, yes, yes, no
+{ushift}, yes, yes, yes
+|===

modules/getting_started/nav.adoc

@@ -0,0 +1,10 @@
+= Getting Started Guide
+
+* xref:introducing.adoc[]
+* xref:installing.adoc[]
+* xref:using.adoc[]
+* xref:configuring.adoc[]
+* xref:networking.adoc[]
+* xref:administrative-tasks.adoc[]
+* xref:troubleshooting.adoc[]
+

modules/getting_started/pages/administrative-tasks.adoc

@@ -0,0 +1,8 @@
+:description: Administrative tasks
+
+[id="administrative-tasks_{context}"]
+= Administrative tasks
+
+include::partial$proc_starting-monitoring.adoc[leveloffset=+1]
+
+include::partial$proc_enabling-override-operators.adoc[leveloffset=+1]

modules/getting_started/pages/configuring.adoc

@@ -0,0 +1,12 @@
+:description: Configuring {prod}
+
+[id="configuring_{context}"]
+= Configuring {prod}
+
+include::partial$con_about-configuration.adoc[leveloffset=+1]
+
+include::partial$proc_viewing-configuration.adoc[leveloffset=+1]
+
+include::partial$proc_changing-the-selected-preset.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-the-instance.adoc[leveloffset=+1]

modules/getting_started/pages/installing.adoc

@@ -0,0 +1,16 @@
+:description: Installing {prod}
+
+[id="installation_{context}"]
+= Installing {prod}
+
+include::partial$ref_minimum-system-requirements.adoc[leveloffset=+1]
+
+include::partial$ref_required-software-packages.adoc[leveloffset=+1]
+
+include::partial$proc_installing.adoc[leveloffset=+1]
+
+include::partial$con_about-usage-data-collection.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-usage-data-collection.adoc[leveloffset=+1]
+
+include::partial$proc_upgrading.adoc[leveloffset=+1]

modules/getting_started/pages/introducing.adoc

@@ -0,0 +1,8 @@
+:description: Introducing  {prod}
+
+[id="introducing_{context}"]
+= Introducing {rh-prod}
+
+include::partial$con_about.adoc[leveloffset=+1]
+
+include::partial$con_differences-from-production-openshift-install.adoc[leveloffset=+1]

modules/getting_started/pages/networking.adoc

@@ -0,0 +1,16 @@
+:description: Networking
+
+[id="networking_{context}"]
+= Networking
+
+include::partial$ref_dns-configuration.adoc[leveloffset=+1]
+
+include::partial$ref_reserved-ip-subnets.adoc[leveloffset=+1]
+
+include::partial$proc_starting-behind-proxy.adoc[leveloffset=+1]
+
+include::partial$proc_connecting-to-host.adoc[leveloffset=+1]
+
+include::partial$proc_setting-up-remote-server.adoc[leveloffset=+1]
+
+include::partial$proc_connecting-to-remote-instance.adoc[leveloffset=+1]

modules/getting_started/pages/troubleshooting.adoc

@@ -0,0 +1,19 @@
+:description: Troubleshooting {prod}
+
+[id="troubleshooting_{context}"]
+= Troubleshooting {rh-prod}
+
+[NOTE]
+====
+The goal of {rh-prod} is to deliver an {ocp} environment for development and testing purposes.
+Issues occurring during installation or usage of specific {openshift} applications are outside of the scope of {prod}.
+Report such issues to the relevant project.
+====
+
+include::partial$proc_getting-shell-access-to-the-openshift-cluster.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-expired-certificates.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-bundle-version-mismatch.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-unknown-issues.adoc[leveloffset=+1]

modules/getting_started/pages/using.adoc

@@ -0,0 +1,16 @@
+[id="using_{context}"]
+= Using {prod}
+
+include::partial$con_about-presets.adoc[leveloffset=+1]
+
+include::partial$proc_setting-up.adoc[leveloffset=+1]
+
+include::partial$proc_starting-the-instance.adoc[leveloffset=+1]
+
+include::partial$assembly_accessing-the-openshift-cluster.adoc[leveloffset=+1]
+
+include::partial$proc_deploying-sample-application-with-odo.adoc[leveloffset=+1]
+
+include::partial$proc_stopping-the-instance.adoc[leveloffset=+1]
+
+include::partial$proc_deleting-the-instance.adoc[leveloffset=+1]

modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc

@@ -0,0 +1,9 @@
+= Accessing the {openshift} cluster
+
+Access the {ocp} cluster running in the {prod} instance by using the {ocp} web console or {openshift} CLI ([command]`oc`).
+
+include::partial$proc_accessing-the-openshift-web-console.adoc[leveloffset=+1]
+
+include::partial$proc_accessing-the-openshift-cluster-with-oc.adoc[leveloffset=+1]
+
+include::partial$proc_accessing-the-internal-openshift-registry.adoc[leveloffset=+1]

modules/getting_started/partials/con_about-configuration.adoc

@@ -0,0 +1,11 @@
+= About {prod} configuration
+
+Use the [command]`{bin} config` command to configure both the [command]`{bin}` executable and the {prod} instance.
+The [command]`{bin} config` command requires a subcommand to act on the configuration.
+The available subcommands are `get`, `set,` `unset`, and `view`.
+The `get`, `set`, and `unset` subcommands operate on named configurable properties.
+Run the [command]`{bin} config --help` command to list the available properties.
+
+You can also use the [command]`{bin} config` command to configure the behavior of the startup checks for the [command]`{bin} start` and [command]`{bin} setup` commands.
+By default, startup checks report an error and stop execution when their conditions are not met.
+Set the value of a property starting with `skip-check` to `true` to skip the check.

modules/getting_started/partials/con_about-presets.adoc

@@ -0,0 +1,17 @@
+= About presets
+
+[role="_abstract"]
+{prod} presets represent a managed container runtime, and the lower bounds of system resources required by the instance to run it.
+{prod} offers presets for:
+
+include::example$snip_{project-context}_preset_list.adoc[]
+
+On {msw} and {mac}, the {prod} guided installer prompts you for your desired preset.
+On Linux, the {ocp} preset is selected by default.
+You can change this selection using the [command]`{bin} config` command before running the [command]`{bin} setup` command.
+Only one preset can be active at a time.
+
+[role="_additional-resources"]
+.Additional resources
+* For more information about the minimum system requirements for each preset, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements].
+* For more information on changing the selected preset, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset].

modules/getting_started/partials/con_about-usage-data-collection.adoc

@@ -0,0 +1,10 @@
+= About usage data collection
+
+{prod} prompts you before use for optional, anonymous usage data collection to assist with development.
+No personally identifiable information is collected.
+Consent for usage data collection can be granted or revoked by you at any time.
+
+[role="_additional-resources"]
+.Additional resources
+* For more information about collected data, see the {rh} link:{telemetry-notice-url}[Telemetry data collection notice].
+* To grant or revoke consent for usage data collection, see link:{crc-gsg-url}#configuring-usage-data-collection_gsg[Configuring usage data collection].

modules/getting_started/partials/con_about.adoc

@@ -0,0 +1,10 @@
+= About {prod}
+
+{rh-prod} brings a minimal {ocp} 4 cluster to your local computer.
+This runtime provides minimal environments for development and testing purposes.
+{prod} is mainly targeted at running on developers' desktops.
+For other {ocp} use cases, such as headless or multi-developer setups, use the link:{openshift-installer-url}[full {openshift} installer].
+
+See the link:{openshift-docs-url-landing-page}[{ocp} documentation] for a full introduction to {ocp}.
+
+{prod} includes the [command]`{bin}` command-line interface (CLI) to interact with the {prod} instance using the desired container runtime.

modules/getting_started/partials/con_differences-from-production-openshift-install.adoc

@@ -0,0 +1,24 @@
+= Differences from a production {ocp} installation
+
+The {openshift} preset for {rh-prod} provides a regular {ocp} installation with the following notable differences:
+
+* **The {ocp} cluster is ephemeral and is not intended for production use.**
+* **{prod} does not have a supported upgrade path to newer {ocp} versions.**
+Upgrading the {ocp} version might cause issues that are difficult to reproduce.
+* It uses a single node, which behaves as both a control plane and worker node.
+* It disables the Cluster Monitoring Operator by default.
+This disabled Operator causes the corresponding part of the web console to be non-functional.
+* It disables the following operators:
+** Cloud Credential Operator.
+** Cluster Autoscaler Operator.
+** Cloud Controller Manager Operator.
+* The {ocp} cluster runs in a virtual machine known as an __instance__.
+This might cause other differences, particularly with external networking.
+
+The {ocp} cluster provided by {prod} also includes the following non-customizable cluster settings.
+These settings should not be modified:
+
+* The ***.crc.testing** domain.
+* The address range used for internal cluster communication.
+** The cluster uses the **172** address range.
+This can cause issues when, for example, a proxy is run in the same address space.