From f76fc1fa14f3702b14d38c9dbb7c0edb9b5c2abc Mon Sep 17 00:00:00 2001
From: Varac <varac@varac.net>
Date: Mon, 16 Aug 2021 22:53:04 +0200
Subject: [PATCH] Split advanced installation and customizing
---
docs/advanced_installation.rst | 69 ----------------------------------
docs/customizing.rst | 68 +++++++++++++++++++++++++++++++++
docs/index.rst | 10 +----
docs/security.rst | 2 +-
docs/upgrading.rst | 4 +-
5 files changed, 72 insertions(+), 81 deletions(-)
create mode 100644 docs/customizing.rst
diff --git a/docs/advanced_installation.rst b/docs/advanced_installation.rst
index afb92a7ea..6db90a4fd 100644
--- a/docs/advanced_installation.rst
+++ b/docs/advanced_installation.rst
@@ -2,14 +2,6 @@
Advanced installation
=====================
-In this guide we show how to customize your cluster installation, i.e. if you
-want to install additional applications, or change the configuration of extisting
-apps installed by OAS this is the right place. Customizing other parts of your
-cluster is possible but not yet covered by this guide.
-As the name of this guide implies, it is written for users with advanced knowledge
-of the tools behind Openappstack, most importantly: Kubernetes, Helm, Ansible and Flux 2.
-
-
.. _setup-with-greenhost-api:
Advanced cluster creation: Setup with the Greenhost API
@@ -102,64 +94,3 @@ Advanced cluster creation: Setup with the Greenhost API
You can now continue to :ref:`step-2`, or :ref:`step-3` if you used the API to
create the DNS records.
-
-Customization
--------------
-
-.. warning::
-
- Customizing your OAS cluster could break your cluster in a way that it's not
- easy to recover. Please be aware of the potential risk when proceeding.
-
-Prerequisites
-=============
-
-* A functional OAS cluster installed following the
- `Openappstack installation instructions <installation_instructions.html>`__
-
-Customize OAS applications
-==========================
-
-Apps deployed by OAS are configured using helm values from templates in
-``flux2/apps/<application>/release.yaml``. It is possible to override values
-from the helmrelease by adding a custom ``ConfigMap`` or ``Secret`` to the
-cluster. The secret or configmap name is specified in the ``valuesFrom`` section
-of the ``release.yaml`` file. Read more in the `Flux documentation
-<https://fluxcd.io/docs/migration/helm-operator-migration/#values-from-sources>`__
-
-Example: Customize Nextcloud to work with staging certificates
---------------------------------------------------------------
-
-Our CI pipeline works with staging certificates from Let's Encrypt, for that
-reason we need to allow insecure connections for the integration with
-ONLYOFFICE. You can find the file at ``install/overrides/oas-nextcloud-override.yaml``.
-
-To apply it, run the following commands:
-
-.. code:: bash
-
- # If you want to run this on your provisioning machine, tell kubectl to use
- # your cluster:
- export KUBECONFIG=$PWD/clusters/oas.example.org/kube_config_cluster.yml
- # Check the current state of the helmrelease you want to modify:
- flux get helmrelease -A
- # If all is OK, make sure to apply your override configmap or secret in the
- # same namespace as your helmrelease with the '-n' argument
- kubectl apply \
- -n oas-apps \
- -f ./install/overrides/oas-nextcloud-override.yaml
-
-Adding custom apps to the cluster
-=================================
-
-OpenAppStack uses Flux 2 to install and auto-update applications. If you want to
-install extra applications or other things into the Kubernetes cluster, our
-advice would be to set up your own GitRepository and add it to the Flux system.
-
-When you do this, you are fully responsible for keeping those applications
-secure and updated. If any of those applications is insecure, that can also
-invalidate the security of your OpenAppStack applications, because they are part
-of the same cluster and VPS.
-
-Refer to the `Flux 2 documentation <https://fluxcd.io/docs>`__ for more
-information.
diff --git a/docs/customizing.rst b/docs/customizing.rst
new file mode 100644
index 000000000..b389c49a7
--- /dev/null
+++ b/docs/customizing.rst
@@ -0,0 +1,68 @@
+===========
+Customizing
+===========
+
+In this guide we show how to customize your cluster installation, i.e. if you
+want to install additional applications, or change the configuration of extisting
+apps installed by OAS this is the right place. Customizing other parts of your
+cluster is possible but not yet covered by this guide.
+This guide is written for users with advanced knowledge of the tools behind
+Openappstack, most importantly: Kubernetes, Helm, Ansible and Flux 2.
+
+.. warning::
+
+ Customizing your OAS cluster could break your cluster in a way that it's not
+ easy to recover. Please be aware of the potential risk when proceeding.
+
+Prerequisites
+=============
+
+* A functional OAS cluster installed following the
+ `Openappstack installation instructions <installation_instructions.html>`__
+
+Customize OAS applications
+==========================
+
+Apps deployed by OAS are configured using helm values from templates in
+``flux2/apps/<application>/release.yaml``. It is possible to override values
+from the helmrelease by adding a custom ``ConfigMap`` or ``Secret`` to the
+cluster. The secret or configmap name is specified in the ``valuesFrom`` section
+of the ``release.yaml`` file. Read more in the `Flux documentation
+<https://fluxcd.io/docs/migration/helm-operator-migration/#values-from-sources>`__
+
+Example: Customize Nextcloud to work with staging certificates
+--------------------------------------------------------------
+
+Our CI pipeline works with staging certificates from Let's Encrypt, for that
+reason we need to allow insecure connections for the integration with
+ONLYOFFICE. You can find the file at ``install/overrides/oas-nextcloud-override.yaml``.
+
+To apply it, run the following commands:
+
+.. code:: bash
+
+ # If you want to run this on your provisioning machine, tell kubectl to use
+ # your cluster:
+ export KUBECONFIG=$PWD/clusters/oas.example.org/kube_config_cluster.yml
+ # Check the current state of the helmrelease you want to modify:
+ flux get helmrelease -A
+ # If all is OK, make sure to apply your override configmap or secret in the
+ # same namespace as your helmrelease with the '-n' argument
+ kubectl apply \
+ -n oas-apps \
+ -f ./install/overrides/oas-nextcloud-override.yaml
+
+Adding custom apps to the cluster
+=================================
+
+OpenAppStack uses Flux 2 to install and auto-update applications. If you want to
+install extra applications or other things into the Kubernetes cluster, our
+advice would be to set up your own GitRepository and add it to the Flux system.
+
+When you do this, you are fully responsible for keeping those applications
+secure and updated. If any of those applications is insecure, that can also
+invalidate the security of your OpenAppStack applications, because they are part
+of the same cluster and VPS.
+
+Refer to the `Flux 2 documentation <https://fluxcd.io/docs>`__ for more
+information.
diff --git a/docs/index.rst b/docs/index.rst
index ea1282f68..d44e31085 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,9 +22,6 @@ For more information, go to `the OpenAppStack website`_.
.. _the OpenAppStack website: https://openappstack.net
-First steps
------------
-
.. toctree::
:maxdepth: 2
:caption: First steps
@@ -34,21 +31,16 @@ First steps
testing
advanced_installation
-Maintenance
------------
-
.. toctree::
:maxdepth: 2
:caption: Maintenance
maintenance
upgrading
+ customizing
troubleshooting
security
-Reference
----------
-
.. toctree::
:maxdepth: 2
:caption: Reference
diff --git a/docs/security.rst b/docs/security.rst
index 64a2240e7..099bfa76a 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -12,7 +12,7 @@ If you like to limit who can access your cluster resources you can configure
the OAS ingress (`ingress-nginx <https://kubernetes.github.io/ingress-nginx>`__)
to only accept connections from a certain IP address or range.
-Follow the :ref:`advanced_installation:Customize OAS applications` instructions, but use the following
+Follow the :ref:`customizing:Customize OAS applications` instructions, but use the following
secret as ``install/overrides/oas-nginx-override.yml`` and apply the secret in
the ``oas`` namespace instead of ``oas-apps``. Replace the source range with the
IP address ranges you want to allow.
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index e8d1f3739..f63b029cf 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -1,5 +1,5 @@
-Upgrading OpenAppStack
-======================
+Upgrading
+=========
Upgrading to 0.7.0
------------------
--
GitLab