docs: Add management and demo docs (#449)

* Add Management and Demo docs

* Update xrefs and formatting

* Fix xref

* Update playbook

* Update discussions link

* Update Makefile

* Fix most internal and external links

* Update playbooks

* Update top navigation

* Add demo navigation

* Update xref in release notes

* Switch back to main branches in playbook

* Fix branch name in playbook

* Remove fixup branches from Hive repo

* Apply suggestions

Co-authored-by: Felix Hennig <fhennig@users.noreply.github.com>

* Remove home component from xrefs

---------

Co-authored-by: Sebastian Bernauer <sebastian.bernauer@stackable.de>
Co-authored-by: Felix Hennig <fhennig@users.noreply.github.com>

Author: 3 people

Makefile

@@ -7,8 +7,8 @@ build:
 
 .PHONY: clean
 clean:
-	rm -r build
+	rm -rf build
 	# 'cache' is the configured cache dir in the playbook
-	rm -r cache
+	rm -rf cache
 
 .PHONY: build

antora-playbook.yml

@@ -21,7 +21,10 @@ content:
       tags: []
       branches: [main, release/*]
     # stackablectl
-    - url: https://github.com/stackabletech/stackablectl.git
+    - url: https://github.com/stackabletech/stackable-cockpit.git
+      start_path: docs
+    # demos
+    - url: https://github.com/stackabletech/demos.git
       start_path: docs
     # internal operators
     - url: https://github.com/stackabletech/commons-operator.git

antora.yml

@@ -4,6 +4,7 @@ title: Stackable Documentation
 nav:
   - modules/ROOT/nav.adoc
   - modules/concepts/nav.adoc
+  - modules/demos/nav.adoc
   - modules/tutorials/nav.adoc
   - modules/reference/nav.adoc
   - modules/operators/nav.adoc

gitpod-antora-playbook.yml

@@ -18,8 +18,11 @@ content:
     - url: /workspace/documentation
       tags: []
       branches: [HEAD, release/*]
-    # stackablectl
-    - url: https://github.com/stackabletech/stackablectl.git
+    # management tools
+    - url: https://github.com/stackabletech/stackable-cockpit.git
+      start_path: docs
+    # demos
+    - url: https://github.com/stackabletech/demos.git
       start_path: docs
     # internal operators
     - url: https://github.com/stackabletech/commons-operator.git

local-antora-playbook.yml

@@ -20,7 +20,10 @@ content:
       tags: []
       branches: [HEAD, release/*]
     # stackablectl
-    - url: https://github.com/stackabletech/stackablectl.git
+    - url: https://github.com/stackabletech/stackable-cockpit.git
+      start_path: docs
+    # demos
+    - url: https://github.com/stackabletech/demos.git
       start_path: docs
     # internal operators
     - url: https://github.com/stackabletech/commons-operator.git

modules/ROOT/pages/getting_started.adoc

@@ -6,7 +6,7 @@ One of the best ways of getting started with a new platform is to try it out. An
 
 Firstly, let’s cover whether this *Getting Started* guide is right for you. This is intended as a learning tool to discover more about Stackable, its deployment and architecture.
 
-* If you want to build a production cluster then this is not for you. This tutorial is to familiarise you with the Stackable architecture and is not a guide for building robust clusters.
+* If you want to build a production cluster then this is not for you. This tutorial is to familiarize you with the Stackable architecture and is not a guide for building robust clusters.
 * This is intended for use in a private network or lab; it doesn't enable many security features such as authentication or encryption and should not be directly connected to the Internet. Be careful if you're deploying in the cloud as your instances may default to using public IPs.
 
 == Overview
@@ -76,7 +76,7 @@ Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-syste
 == Installing Stackable
 === Install stackablectl
 
-Install the Stackable command line utility xref:stackablectl::index.adoc[stackablectl] by following the installation steps for your platform on the xref:stackablectl::installation.adoc[installation] page.
+Install the Stackable command line utility xref:management:stackablectl:index.adoc[stackablectl] by following the installation steps for your platform on the xref:management:stackablectl:installation.adoc[installation] page.
 
 === Installing Stackable Operators
 The Stackable operators are components that translate the service definitions deployed via Kubernetes into deploy services on the worker nodes. These can be installed on any node that has access to the Kubernetes control plane. In this example we will install them on the controller node.

modules/ROOT/pages/index.adoc

@@ -1,8 +1,14 @@
 = Stackable Documentation
 :page-layout: landing
 
+:k8s-operators: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
+:docs-discussion: https://github.com/stackabletech/community/discussions
+:docs-issues: https://github.com/stackabletech/documentation/issues
+:docs-repo: https://github.com/stackabletech/documentation
+
 Welcome to Stackable!
-This documentation gives you an overview of the Stackable Data Platform, how to install and manage it as well as some tutorials.
+This documentation gives you an overview of the Stackable Data Platform, how to install and manage it as well as some
+tutorials.
 
 ++++
 <div class="boxes two-column">
@@ -16,11 +22,14 @@ This documentation gives you an overview of the Stackable Data Platform, how to
 <h3>Introduction</h3>
 ++++
 
-The Stackable Data Platform allows you to deploy, scale and manage Data infrastructure in any environment running https://kubernetes.io/[Kubernetes].
+The Stackable Data Platform allows you to deploy, scale and manage Data infrastructure in any environment running
+https://kubernetes.io/[Kubernetes].
 
-You can find an overview of the supported components <<Components,below>>, as well as a full list of all supported product versions xref:operators:supported_versions.adoc[here].
+You can find an overview of the supported components <<Components,below>>, as well as a full list of all supported
+product versions xref:operators:supported_versions.adoc[here].
 
-If you have any feedback regarding the documentation please either open an https://github.com/stackabletech/documentation/issues[issue], ask a https://github.com/stackabletech/documentation/discussions[question] or look at the source for this documentation in its https://github.com/stackabletech/documentation[repository].
+If you have any feedback regarding the documentation please either open an {docs-issues}[issue], ask a
+{docs-discussion}[question] or look at the source for this documentation in its {docs-repo}[repository].
 
 ++++
 </div>
@@ -34,16 +43,20 @@ If you have any feedback regarding the documentation please either open an https
 <h3>Goal of the project</h3>
 ++++
 
-We are building a distribution of existing Open Source tools that together comprise the components of a modern data platform.
+We are building a distribution of existing Open Source tools that together comprise the components of a modern data
+platform.
 
-There are components to ingest data, to store data, to process and visualize and much more.
-While the platform got started in the _Big Data_ ecosystem we are in no way limited to big data workloads.
+There are components to ingest data, to store data, to process and visualize and much more. While the platform got
+started in the _Big Data_ ecosystem we are in no way limited to big data workloads.
 
-You can declaratively build these environments, and we don't stop at the tool level as we also provide ways for the users to interact with the platform in the "as Code"-approach.
+You can declaratively build these environments, and we don't stop at the tool level as we also provide ways for the
+users to interact with the platform in the "as Code"-approach.
 
 We are leveraging the https://www.openpolicyagent.org/[Open Policy Agent] to provide Security-as-Code.
 
-We are building a distribution that includes the “best of breed” of existing Open Source tools, but bundles them in a way, so it is easy to deploy a fully working stack of software. Most of the existing tools are “single purpose” tools, which often do not play nicely together out-of-the-box.
+We are building a distribution that includes the “best of breed” of existing Open Source tools, but bundles them in a
+way, so it is easy to deploy a fully working stack of software. Most of the existing tools are “single purpose” tools,
+which often do not play nicely together out-of-the-box.
 
 ++++
 </div>
@@ -55,10 +68,8 @@ We are building a distribution that includes the “best of breed” of existing
 
 == Components
 
-We are using Kubernetes as our deployment platform.
-And we're building https://kubernetes.io/docs/concepts/extend-kubernetes/operator/[Operators] for each of the products we support.
-
-The Stackable Data Platform supports the following products:
+We are using Kubernetes as our deployment platform. And we're building {k8s-operators}[Operators] for each of the
+products we support. The Stackable Data Platform supports the following products:
 
 ++++
 <br>
@@ -78,7 +89,7 @@ The Stackable Data Platform supports the following products:
 
 Airflow is a workflow engine and your replacement should you be using Apache Oozie.
 
-xref:airflow::index.adoc[Read more]
+xref:airflow:index.adoc[Read more]
 
 ++++
 </div>
@@ -94,7 +105,7 @@ xref:airflow::index.adoc[Read more]
 
 Apache Druid is a real-time database to power modern analytics applications.
 
-xref:druid::index.adoc[Read more]
+xref:druid:index.adoc[Read more]
 
 ++++
 </div>
@@ -110,7 +121,7 @@ xref:druid::index.adoc[Read more]
 
 HBase is a distributed, scalable, big data store.
 
-xref:hbase::index.adoc[Read more]
+xref:hbase:index.adoc[Read more]
 
 ++++
 </div>
@@ -126,7 +137,7 @@ xref:hbase::index.adoc[Read more]
 
 HDFS is a distributed file system that provides high-throughput access to application data.
 
-xref:hdfs::index.adoc[Read more]
+xref:hdfs:index.adoc[Read more]
 
 ++++
 </div>
@@ -140,9 +151,10 @@ xref:hdfs::index.adoc[Read more]
 <h3 id="hive"><a class="anchor" href="#hive"></a>Apache Hive</h3>
 ++++
 
-The Apache Hive data warehouse software facilitates reading, writing, and managing large datasets residing in distributed storage using SQL. We support the Hive Metastore.
+The Apache Hive data warehouse software facilitates reading, writing, and managing large datasets residing in
+distributed storage using SQL. We support the Hive Metastore.
 
-xref:hive::index.adoc[Read more]
+xref:hive:index.adoc[Read more]
 
 ++++
 </div>
@@ -156,9 +168,10 @@ xref:hive::index.adoc[Read more]
 <h3 id="kafka"><a class="anchor" href="#kafka"></a>Apache Kafka</h3>
 ++++
 
-Apache Kafka is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications.
+Apache Kafka is an open-source distributed event streaming platform used by thousands of companies for high-performance
+data pipelines, streaming analytics, data integration, and mission-critical applications.
 
-xref:kafka::index.adoc[Read more]
+xref:kafka:index.adoc[Read more]
 
 ++++
 </div>
@@ -174,7 +187,7 @@ xref:kafka::index.adoc[Read more]
 
 An easy to use, powerful, and reliable system to process and distribute data.
 
-xref:nifi::index.adoc[Read more]
+xref:nifi:index.adoc[Read more]
 
 ++++
 </div>
@@ -188,9 +201,10 @@ xref:nifi::index.adoc[Read more]
 <h3 id="spark"><a class="anchor" href="#spark"></a>Apache Spark</h3>
 ++++
 
-Apache Spark is a multi-language engine for executing data engineering, data science, and machine learning on single-node machines or clusters.
+Apache Spark is a multi-language engine for executing data engineering, data science, and machine learning on
+single-node machines or clusters.
 
-xref:spark-k8s::index.adoc[Read more]
+xref:spark-k8s:index.adoc[Read more]
 
 ++++
 </div>
@@ -206,7 +220,7 @@ xref:spark-k8s::index.adoc[Read more]
 
 Apache Superset is a modern data exploration and visualization platform.
 
-xref:superset::index.adoc[Read more]
+xref:superset:index.adoc[Read more]
 
 ++++
 </div>
@@ -222,7 +236,7 @@ xref:superset::index.adoc[Read more]
 
 Fast distributed SQL query engine for big data analytics that helps you explore your data universe.
 
-xref:trino::index.adoc[Read more]
+xref:trino:index.adoc[Read more]
 
 ++++
 </div>
@@ -236,9 +250,10 @@ xref:trino::index.adoc[Read more]
 <h3 id="zookeeper"><a class="anchor" href="#zookeeper"></a>Apache ZooKeeper</h3>
 ++++
 
-ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.
+ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed
+synchronization, and providing group services.
 
-xref:zookeeper::index.adoc[Read more]
+xref:zookeeper:index.adoc[Read more]
 
 ++++
 </div>

modules/ROOT/pages/quickstart.adoc

@@ -1,6 +1,9 @@
 = Quickstart
 
-This is the super-short getting started guide that should enable you to get something up and running in less than three minutes (excluding download times).
+:cockpit-releases: https://github.com/stackabletech/stackable-cockpit/releases
+
+This is the super-short getting started guide that should enable you to get something up and running in less than three
+minutes (excluding download times).
 
 == Setup
 
@@ -10,7 +13,7 @@ On Linux (Windows and MacOS instructions below):
 
 [source,console]
 ----
-$ curl -L -o stackablectl https://github.com/stackabletech/stackablectl/releases/latest/download/stackablectl-x86_64-unknown-linux-gnu
+$ curl -L -o stackablectl https://github.com/stackabletech/stackable-cockpit/releases/latest/download/stackablectl-x86_64-unknown-linux-gnu
 ----
 
 and mark it as executable:
@@ -23,9 +26,9 @@ $ chmod +x stackablectl
 .Instruction for Windows and MacOS
 [%collapsible]
 ====
-Download `stackablectl-x86_64-pc-windows-gnu.exe` (for Windows) or `stackablectl-x86_64-apple-darwin` (Mac OS Intel) or `stackablectl-aarch64-apple-darwin` (MacOS ARM) from the https://github.com/stackabletech/stackablectl/releases/latest[latest release] and save it as `stackablectl`.
-
-For windows, you can simply execute it. For MacOS mark it as executable:
+Download `stackablectl-x86_64-pc-windows-gnu.exe` (for Windows) or `stackablectl-x86_64-apple-darwin` (Mac OS Intel) or
+`stackablectl-aarch64-apple-darwin` (MacOS ARM) from the {cockpit-releases}[latest release] and save it as
+`stackablectl`. For Windows, you can simply execute it. For MacOS mark it as executable:
 
 [source,console]
 ----
@@ -34,19 +37,22 @@ $ chmod +x stackablectl
 
 If you want to execute it from anywhere in your system, you need to add it to the system `PATH`.
 
-NOTE: If macOS denies the execution of stackablectl go to `Settings` -> `Security & Privacy` -> `General`. Here you will see a pop up asking if you want to allow access for `stackablectl`. You must allow access.
+NOTE: If macOS denies the execution of stackablectl go to `Settings` -> `Security & Privacy` -> `General`. Here you will
+see a pop up asking if you want to allow access for `stackablectl`. You must allow access.
 ====
 
 == Install the Taxi data demo
 
-The xref:stackablectl::demos/trino-taxi-data.adoc[`trino-taxi-data`] Demo installs the latest Stackable platform release and a visualization of https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page[New York City Taxi Data] using Trino and Superset:
+The xref:demos:trino-taxi-data.adoc[`trino-taxi-data`] Demo installs the latest Stackable platform release and a
+visualization of https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page[New York City Taxi Data] using Trino and
+Superset:
 
 [source,console]
 ----
 ./stackablectl demo install trino-taxi-data
 ----
 
-TIP: Learn more about this demo in the demo docs: xref:stackablectl::demos/trino-taxi-data.adoc[]
+TIP: Learn more about this demo in the demo docs: xref:demos:trino-taxi-data.adoc[]
 
 == Connect
 
@@ -78,4 +84,5 @@ It will output something like:
                                    console-http        http://172.18.0.3:30503   Admin user: admin, password: adminadmin
 ----
 
-To connect to Superset, open the listed endpoint in your browser and log in with the username `admin` and the password `adminadmin`.
+To connect to Superset, open the listed endpoint in your browser and log in with the username `admin` and the password
+`adminadmin`.