Merge pull request #5 from themr0c/fix-cross-references

chore: fix internal links, simplify source code and publication

.asciidoctorconfig

@@ -0,0 +1,10 @@
+// .asciidoctorconfig
+// Specifies Asciidoctor configuration to preview files in the editor
+// See: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html
+
+:docinfo: shared
+:docinfodir: {asciidoctorconfigdir}/.asciidoctor
+:toc:
+:linkcss:
+:stylesdir: https://crc.dev/docs/_/css/
+:stylesheet: site.css

antora-playbook.yml

@@ -1,7 +1,7 @@
 ---
 site:
   title: CRC Documentation
-  start_page: getting_started:getting_started:introducing.adoc
+  start_page: ROOT::introducing.adoc
   url: https://crc.dev/docs
   robots: allow
 content:
@@ -55,10 +55,8 @@ asciidoc:
     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"

antora.yml

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

modules/ROOT/pages/administrative-tasks.adoc

@@ -0,0 +1,70 @@
+:description: Administrative tasks
+= Administrative tasks
+
+== Starting monitoring
+
+{prod} disables cluster monitoring by default to ensure that {prod} can run on a typical notebook.
+Monitoring is responsible for listing your cluster in the link:https://console.redhat.com/openshift[Red Hat Hybrid Cloud Console].
+Follow this procedure to enable monitoring for your cluster.
+
+.Prerequisites
+* You must assign additional memory to the {prod} instance.
+At least 14 GiB of memory, a value of `14336`, is recommended for core functionality.
+Increased workloads will require more memory.
+For more information, see xref:configuring.adoc#configuring-the-instance[Configuring the instance].
+
+.Procedure
+. Set the `enable-cluster-monitoring` configurable property to `true`:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config set enable-cluster-monitoring true
+----
+
+. Start the instance:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} start
+----
++
+[WARNING]
+====
+Cluster monitoring cannot be disabled.
+To remove monitoring, set the `enable-cluster-monitoring` configurable property to `false` and delete the existing {prod} instance.
+====
+
+== Enabling override Operators
+
+To verify {prod} can run on a typical notebook, some resource-heavy services get disabled by default.
+These services can be enabled by manually removing the desired Operator from the Operator override list.
+
+.Prerequisites
+* A running {prod} virtual machine and a working [command]`oc` command.
+For more information, see xref:using.adoc#accessing-the-openshift-cluster-with-the-openshift-cli[Accessing the OpenShift cluster with `oc`].
+* You must log in through [command]`oc` as the `kubeadmin` user.
+
+.Procedure
+. List unmanaged Operators and note the numeric index for the desired Operator:
+
+** On Linux or {mac}:
++
+[subs="+quotes"]
+----
+$ oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | nl -v -2
+----
+
+** On {msw} using PowerShell:
++
+[subs="+quotes"]
+----
+PS> oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | % {$nl++;"`t$($nl-3) `t $_"};$nl=0
+----
+
+. Start the desired Operator using the identified numeric index:
++
+[subs="+quotes"]
+----
+$ oc patch clusterversion/version --type='json' -p '[{"op":"remove", "path":"/spec/overrides/_<unmanaged-operator-index>_"}]'
+clusterversion.config.openshift.io/version patched
+----

modules/ROOT/pages/configuring.adoc

@@ -0,0 +1,138 @@
+:description: Configuring {prod}
+= Configuring {prod}
+
+[id='about-configuration']
+== 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.
+
+[id='viewing-configuration']
+== Viewing {prod} configuration
+
+The {prod} executable provides commands to view configurable properties and the current {prod} configuration.
+
+.Procedure
+. To view the complete current configuration diverting from default values:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config view
+----
+
+. To list the available configurable properties:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config --help
+----
+
+. To view the values for a configurable property:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config get _<property>_
+----
+
+[id='changing-the-selected-preset']
+== Changing the selected preset
+
+You can change the container runtime used for the {prod} instance by selecting the desired preset before creating the instance.
+
+You cannot change the preset of an existing {prod} instance.
+
+.Procedure
+. Change the selected preset from the command line:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config set preset __<name>__
+----
++
+Valid preset names are:
++
+.Preset names
+[%header,format=csv,cols="1,2"]
+|===
+Name, Preset
+`openshift`, {ocp}
+`okd`, {okd}
+`microshift`, {ushift}
+|===
+
+. Save any desired information stored in your existing instance.
+
+. Delete the existing {prod} instance.
++
+[subs="+quotes,attributes"]
+----
+$ {bin} delete
+----
+
+. Start the new {prod} instance:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} start
+----
+
+[id='configuring-the-instance']
+== Configuring the instance
+
+Use the `cpus` and `memory` properties to configure the default number of vCPUs and amount of memory available to the {prod} instance, respectively.
+
+Alternatively, the number of vCPUs and amount of memory can be assigned using the `--cpus` and `--memory` flags to the `{bin} start` command, respectively.
+
+[IMPORTANT]
+====
+You cannot change the configuration of a running {prod} instance.
+To enable configuration changes, you must stop the running instance and start it again.
+====
+
+.Procedure
+. To configure the number of vCPUs available to the instance:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config set cpus __<number>__
+----
++
+The default value for the `cpus` property is `4`.
+The number of vCPUs to assign must be greater than or equal to the default.
+
+. To start the instance with the desired number of vCPUs:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} start --cpus __<number>__
+----
+
+. To configure the memory available to the instance:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} config set memory __<number-in-mib>__
+----
++
+[NOTE]
+====
+Values for available memory are set in mebibytes (MiB).
+One gibibyte (GiB) of memory is equal to 1024 MiB.
+====
++
+The default value for the `memory` property is `10752`.
+The amount of memory to assign must be greater than or equal to the default.
+
+. To start the instance with the desired amount of memory:
++
+[subs="+quotes,attributes"]
+----
+$ {bin} start --memory __<number-in-mib>__
+----