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: ./public

.htmltest.yml

@@ -0,0 +1,10 @@
+---
+# Configuration file for htmltest
+# See: https://github.com/wjdp/htmltest
+
+DirectoryPath: ./public
+OutputDir: .cache/htmltest
+CacheExpires: "12h" # Default is 2 weeks.
+ExternalTimeout: 60 # (seconds) default is 15.
+IgnoreURLs:
+  - https://crc.dev/crc

.vale.ini

@@ -0,0 +1,14 @@
+# Vale configuration file for `che-docs` repository.
+# See: https://docs.errata.ai/vale/config
+
+StylesPath = .cache/vale
+Packages = RedHat
+MinAlertLevel = warning
+
+[*.adoc]
+BasedOnStyles = RedHat
+RedHat.Annotations = suggestion
+RedHat.Headings = suggestion
+RedHat.Slash = warning
+RedHat.Usage = suggestion
+RedHat.Spelling = suggestion

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 ?= public
+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 ?= ./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_DIR):/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-playbook.yml

@@ -0,0 +1,69 @@
+---
+site:
+  title: CRC Documentation
+  start_page: getting_started:getting_started:introducing.adoc
+  url: https://crc.dev/docs
+  robots: allow
+content:
+  sources:
+    - url: ./ # Point to Git repository
+      branches: HEAD # Use local conntent
+      edit_url: "https://github.com/crc-org/crc/edit/main/{path}"
+      start_path: . # Point to docs content
+output:
+  clean: true # Delete stale content
+  dir: public
+runtime:
+  cache_dir: .cache/antora # Use a local directory rather than $HOME
+  log:
+    failure_level: warn # Fail on missing attributes
+    level: debug # Extra verbose
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+urls:
+  html_extension_style: indexify
+  redirect_facility: static
+antora:
+  extensions:
+    - "@antora/lunr-extension"
+    - ./extensions/get-versions.js
+asciidoc:
+  sourcemap: true
+  attributes:
+    icons: font
+    nbsp: " "
+    project-context: crc
+    # Platforms
+    rh: "Red{nbsp}Hat"
+    rhel: "Red{nbsp}Hat Enterprise{nbsp}Linux"
+    fed: Fedora
+    centos: CentOS
+    mac: macOS
+    msw: Microsoft Windows
+    debian: Debian
+    ubuntu: Ubuntu
+    openshift: OpenShift
+    ocp: OpenShift Container Platform
+    okd: OKD
+    ushift: MicroShift
+    # Product naming
+    prod: CRC
+    rh-prod: CRC
+    bin: crc
+    # Documentation naming
+    context: crc
+    crc-gsg: CRC Getting Started Guide
+    # URLs
+    crc-download-url: https://console.redhat.com/openshift/create/local
+    crc-gsg-url: https://crc.dev/crc/
+    openshift-installer-url: https://console.redhat.com/openshift/create
+    openshift-docs-url: https://docs.openshift.com/container-platform/latest
+    openshift-docs-url-landing-page: "{openshift-docs-url}/welcome/index.html#developer-activities"
+    oc-download-url: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/
+    odo-docs-url: https://odo.dev/docs/introduction
+    odo-docs-url-installing: https://odo.dev/docs/overview/installation
+    telemetry-notice-url: https://developers.redhat.com/article/tool-data-collection
+    rhel-resolved-docs: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/using-different-dns-servers-for-different-domains_configuring-and-managing-networking

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.