From acfce116b518681d112205e0a3e3c6bd9896e61f 2024-02-26 11:15:00
From: RhodeCode Admin <admin@rhodecode.com>
Date: 2024-02-26 11:15:00
Subject: [PATCH] docs(install): updated docs for installation topics

---

diff --git a/docs/source/conf.py b/docs/source/conf.py
index f3675f3..aeac692 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -73,6 +73,7 @@ rst_epilog = '''
 .. |authtoken| replace:: Authentication Token
 .. |authtokens| replace:: **Auth Tokens**
 .. |RCC| replace:: RhodeCode Control
+.. |RCS| replace:: RhodeCode rcstack
 .. |RCE| replace:: RhodeCode Enterprise
 .. |RCCE| replace:: RhodeCode Community
 .. |RCEE| replace:: RhodeCode Enterprise
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3f23fee..5f88308 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -132,6 +132,9 @@ There are two requirements for OS to be able to run whole rcstack.
 
     install/installation.rst
     install/upgrade.rst
+    install/rollback-an-upgrade.rst
+    install/custom-database-use.rst
+    install/install-advanced.rst
 
 
 .. toctree::
diff --git a/docs/source/install/custom-database-use.rst b/docs/source/install/custom-database-use.rst
new file mode 100644
index 0000000..adc11d6
--- /dev/null
+++ b/docs/source/install/custom-database-use.rst
@@ -0,0 +1,36 @@
+.. _custom-database-use:
+
+Custom Database usage
+---------------------
+
+.. important::
+
+   If you do change the default database that |RCS| uses, then you will need to
+   manage and upgrade the database by yourself. |RCS| cannot perform normal operations based on an external database.
+
+If you need to change database connection details for a |RCEE| instance,
+use the following steps:
+
+1. Open the :file:`rhodecode.ini` file for the instance you wish to edit. The
+   default location is
+   :file:`config/_shared/rhodecode.ini`
+
+2. When you open the file, find the database configuration section,
+   and use the below example to change the
+   connection details:
+
+.. code-block:: ini
+
+    #########################################################
+    ### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG    ###
+    #########################################################
+
+    # Default SQLite config
+    sqlalchemy.db1.url = sqlite:////home/brian/.rccontrol/enterprise-1/rhodecode.db
+
+    # Use this example for a PostgreSQL
+    sqlalchemy.db1.url = postgresql://postgres:qwe@localhost/rhodecode
+
+    # see sqlalchemy docs for other advanced settings
+    sqlalchemy.db1.echo = false
+    sqlalchemy.db1.pool_recycle = 3600
diff --git a/docs/source/install/install-advanced.rst b/docs/source/install/install-advanced.rst
new file mode 100644
index 0000000..ac5c453
--- /dev/null
+++ b/docs/source/install/install-advanced.rst
@@ -0,0 +1,12 @@
+.. _install-advanced:
+
+
+Advanced Installation
+---------------------
+
+
+.. tip::
+
+   If using a non-SQLite database, install and configure the database, create
+   a new user, and grant permissions.
+
diff --git a/docs/source/install/installation.rst b/docs/source/install/installation.rst
index 84370a6..94b16ca 100644
--- a/docs/source/install/installation.rst
+++ b/docs/source/install/installation.rst
@@ -39,6 +39,7 @@ rcstack is using the below command to install docker, if you prefer to install i
     curl https://get.docker.com/ | sh
 
 
+.. _quick_installation:
 
 Quick install tutorial
 ----------------------
@@ -47,6 +48,14 @@ Those are step-by-step installation/run steps.
 
 1. **initialize; create configurations / docker definitions**
 
+.. note::
+
+    IMPORTANT: A valid domain needs to be set during bootstrap. This is stored inside :file:`.custom/.runtime.env` file.
+    To access the RhodeCode stack running the domain needs to be entered in the browser.
+    This can be a local domain entry or real domain, e.g rhodecode.local or rhodecode.yourcompany.com (pointing to the machine IP)
+    In case your browser can't resolve the given domain, a 404 page will be shown, and rcstack won't router traffic into instances.
+
+
 Run the following command
 
 .. code-block:: bash
@@ -61,14 +70,8 @@ Few adjustments that could be done are for example to change the domain address,
 
 2. **Start router to handle all incoming traffic**
 
-Start Traefik router that would handle all incoming traffic, load balance.
-
-.. note::
+Start Traefik router that would handle all incoming traffic, and load balance it to various components.
 
-    IMPORTANT: A valid domain needs to be set during bootstrap. This is stored inside .custom/.runtime.env file.
-    To access the RhodeCode stack running the domain needs to be entered in the browser.
-    This can be a local entry or real domain, e.g rhodecode.local or rhodecode.yourcompany.com (pointing to the machine IP)
-    In case machine can't resolve the domain, a 404 page will be shown
 
 .. note::
 
@@ -93,7 +96,7 @@ Run the router stack in the background
 .. note::
 
     By default RhodeCode stack is configured to run PostgreSQL database inside docker. If you need to run mysql, or external
-    database, please disable the database inside services stack. :see: configuration of database
+    database, please disable the database inside services stack. :ref:`custom-database-use`
 
 
 4. **Start other services required**
diff --git a/docs/source/install/rollback-an-upgrade.rst b/docs/source/install/rollback-an-upgrade.rst
new file mode 100644
index 0000000..4cdb43b
--- /dev/null
+++ b/docs/source/install/rollback-an-upgrade.rst
@@ -0,0 +1,9 @@
+.. _rollback-an-upgrade:
+
+
+Rollback to previous version
+============================
+
+
+Sometimes it might happen that there’s a need to rollback an performed upgrade of your installed instances.
+