docs: updated few instructions

docs/source/configuration/set-specific-install-version.rst

@@ -0,0 +1,28 b''
+
+============================
+Set Specific Install Version
+============================
+
+By default rcstack uses a defined version stored under :file:`.custom/.runtime.env`
+
+Check current version by running this command:
+
+.. code-block:: bash
+
+    ./rcstack cli image-info --verbose
+    Image stored version: 4.28.0
+    Image from runtime: beta
+    runtime-file=/home/rhodecode-docker/.custom/.runtime.env
+    RC_VERSION=beta
+
+
+When self-update is executed the downloaded stored version gets updated. In case a downgrade, or specific
+version installation is required you can manually set a update version.
+
+
+.. code-block:: bash
+
+    ./rcstack cli set-runtime-image 5.1.0
+
+This will set the runtime version to 5.1.0. Other options can be used that corresponds to the docker release tags.
+e.g `beta` or `edge` to always run on the latest images

README.md

@@ -1,208 +1,208 b''
-# RhodeCode Cluster
+# Welcome to RhodeCode rcstack documentation!
 
-RhodeCode Cluster is a multi-node highly-scalable setup to run RhodeCode services.
-It consists of Edge Router(Traefik with optional SSL) and Metrics Stack (Prometheus, Loki, Grafana) and
-all its additional components in single environment using Docker.
+RhodeCode rcstack is a multi-node highly-scalable setup to run RhodeCode services.
+It consists of all RhodeCode services required with additionally
+Edge Router(Traefik with optional SSL) and Metrics Stack (Prometheus, Loki, Grafana) in single environment using Docker.
 
 Using a docker-compose this setup creates following services for RhodeCode:
 
-Edge-Router (Mandatory):
+Router (mandatory to run):
 
  - Traefik, Edge Router, SSL termination etc.
    Traefik listens to few defaults ports and handles all incomming/outgoing traffic to the stack
  
 Core Services:
 
  - Database (defaults to PostgreSQL)
    Optionally can be replaced by MySQL, or own external database if needed.
  - Redis, acts as cache and queue exchange
  - ChannelStream - live websocket communications
  - Elasticsearch (full text search backend)
  - Nginx (static file service) proxy serving RhodeCode static files
  
 RhodeCode
 
  - RhodeCode CE/EE web app
  - VCSServer for GIT/SVN/HG support
  - SSH server for cloning over SSH
  - SVN webserver for HTTP support over SVN
  - Celery workers for asynchronous tasks
  - Celery beat for automation tasks
 
 Metrics
 
  - Loki, logs aggregation
  - Grafana, metrics Dashboard
  - Prometheus, metrics time-series
  - Statsd-exporter - statsd to Prometheus bridge
  - Node-exporter - machine stats and usage
  - Promtail - log scraping
 
-##rcstack for Linux, docker based installer
+## rcstack for Linux, docker based installer
 
  To get started with RhodeCode get the new shell installer called rcstack
 
 ```
 mkdir docker-rhodecode && cd docker-rhodecode
 curl -L -s -o rcstack https://dls.rhodecode.com/get/master && chmod +x rcstack
 ./rcstack get-started
 ```
 
 ## Pre requisites
 
 To Run this stack Docker engine and Docker Compose needs to be installed on the host machine.
 Please run `./rcstack init` to install docker using the installer, or 
 visit docker site and install docker (min version 20.10) and docker compose:
 
 - https://docs.docker.com/engine/install/
 - https://docs.docker.com/compose/install/ 
 
 If there's docker already installed, rcstack will detect that and skip docker installation
 
 
 # Quick install tutorial
 
 Those are step-by-step installation/run steps.
 
  create configurations / docker definitions:
     
     ./rcstack init
 
 
  At this point a custom file under .custom/.runtime.env was created. Adjust it if required.
  Few adjustments that could be done is to change the domain
 
  Start Traefik router that would handle all incoming traffic, load balance. 
  
  - IMPORTANT: A valid domain needs to be present in .custom/.runtime.env to access the RhodeCode
    This can be a local entry or real domain, e.g rhodecode.local/rhodecode.yourcompany.com (pointing to the machine IP) 
 
  - IMPORTANT: router binds to some common ports 80, 443, SSH (9022), Loki (3100) if those are 
    not available, please adjust them inside the override docker file
 
 
     ./rcstack stack router up --detach
  
  Start the database and bootstrap it
 
 
     ./rcontrol stack database up --detach
  
  Start other services required
 
 
     ./rcstack stack services up --detach
 
  Start RhodeCode stack
 
 
     ./rcstack stack rhodecode up --detach
 
  Check stack status
 
     ./rcstack status
 
  Output should look similar to this:
 
     ---
     CONTAINER ID   IMAGE                                   STATUS                        NAMES                                 PORTS
     ef54fc528e3a   traefik:v2.9.5                          Up 2 hours             rc_cluster_router-traefik-1           0.0.0.0:80->80/tcp, :::80->80/tcp
     f3ea0539e8b0   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-rhodecode-1           0.0.0.0:10020->10020/tcp, :::10020->10020/tcp
     2be52ba58ffe   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-vcsserver-1
     7cd730ad3263   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-celery-1
     dfa231342c87   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-celery-beat-1
     d3d76ce2de96   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-sshd-1
     daaac329414b   rhodecode/rhodecode-ee:4.28.0           Up 2 hours (healthy)   rc_cluster_apps-svn-1
     7b8504fb9acb   nginx:1.23.2                            Up 2 hours (healthy)   rc_cluster_services-nginx-1           80/tcp
     7279c25feb6b   elasticsearch:6.8.23                    Up 2 hours (healthy)   rc_cluster_services-elasticsearch-1   9200/tcp, 9300/tcp
     19fb93587493   redis:7.0.5                             Up 2 hours (healthy)   rc_cluster_services-redis-1           6379/tcp
     fb77fb6496c6   channelstream/channelstream:0.7.1       Up 2 hours (healthy)   rc_cluster_services-channelstream-1   8000/tcp
     cb6c5c022f5b   postgres:14.6                           Up 2 hours (healthy)   rc_cluster_services-database-1        5432/tcp
 
 At this point you should be able to access:
 
 - RhodeCode instance at your domain, e.g rhodecode.local, the default access 
   credentials are generated in .runtime.env 
     ```
     RHODECODE_USER_NAME=admin
     RHODECODE_USER_PASS=super-secret-password
     ```
 
 - Grafana monitoring dashboard at rhodecode.local/_grafana, grafana generates default access credentials
   those need to be changed after first login 
     ```
     user: admin
     pass: admin
     ```
 
 # Operation
 
 ## Data structure / volumes
 
 There are 4 main volumes defined:
 
 
 - `/etc/rhodecode/conf`
   
   Shared volume used for configuration files for rhodecode, vcsserver and supervisord, and some cache data
   rhodecode.ini and vcsserver.ini files are located there and can be adjusted 
 
 - `/var/opt/rhodecode_repo_store` 
 
   Used for main repository storage where repositories would be stored
   
 - `/var/opt/rhodecode_data` 
   
   Data dir for rhodecode cache/lock files, or user sessions (for file backend)
 
 
 ## Set License for EE version
 
 In order to install EE edition a license file is required to be present.
 It can contain your current license, or when empty license can be applied via Web interface.
 
 To apply it during build phase save your raw license data into a file 
 
 `config/rhodecode_enterprise.license` 
 
 If this file is present build phase will read it and license will be applied at creation.
 This file can also be empty and license can be applied via a WEB interface after first login.
 
 
 ## scaling to handle more traffic
 In case for bigger setups docker-compose can scale more rhodecode/vcsserver workers:
 Adjust the .custom/docker-compose-apps.override.yaml file and change
 
 ```
 services:
   rhodecode:
     deploy:
       # set number of instances of services to be spawned on stack start
       replicas: 4
 
   vcsserver:
     deploy:
       # set number of instances of services to be spawned on stack start
       replicas: 6
 ```
 
 Logging is pushed to stdout from all services.
 
 
 ### Upgrade procedure:
 
 - run ./rcstack self-update
 - run ./rcstack stack-upgrade to get upgrade instructions
 
 
 With this done, you can now proceed with every step of normal source installation (Creating & building images), but instead of using
 just `docker-compose` command it needs to be replaced with `docker-compose -f docker-compose.yaml -f docker-compose.source.yaml`
 
 For example to override the installer build with the source `rhodecode` based image, and also setting proper version, run:
 
 ```
 RC_VERSION="4.28.0.SRC.2022.12.12.1" docker-compose -f docker-compose-apps.yaml -f docker-compose.source.yaml build --no-cache --progress=plain rhodecode
 ```
 
 NOTE THAT it's recommended to keep rc_version and source_Ver the same
 

docs/source/conf.py

@@ -1,36 +1,55 b''
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import datetime
 
 now = datetime.datetime.today()
 
 project = 'RhodeCode rcstack'
 copyright = f'2010-{now.year}, RhodeCode Inc.'
 author = 'RhodeCode Inc.'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     'sphinx_rtd_theme'
 ]
 
 templates_path = ['_templates']
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'furo'
 html_static_path = ['_static']
 html_last_updated_fmt = ' %H:%m %b %d, %Y'
 html_show_sphinx = False
 html_extra_path = ['extra']
+
+
+rst_epilog = '''
+.. |RCCEshort| replace:: Community
+.. |RCEEshort| replace:: Enterprise
+.. |git| replace:: Git
+.. |hg| replace:: Mercurial
+.. |svn| replace:: Subversion
+
+.. |RCC| replace:: RhodeCode Control
+.. |RCE| replace:: RhodeCode Enterprise
+.. |RCCE| replace:: RhodeCode Community
+.. |RCEE| replace:: RhodeCode Enterprise
+.. |RCT| replace:: RhodeCode Tools
+
+.. |RCEBOLD| replace:: **RhodeCode Enterprise**
+.. |RCEITALICS| replace:: `RhodeCode Enterprise`
+
+'''

docs/source/index.rst

@@ -1,122 +1,123 b''
 Welcome to RhodeCode rcstack documentation!
 ===========================================
 
 
 =================
 RhodeCode rcstack
 =================
 
 RhodeCode rcstack is a multi-node highly-scalable setup to run RhodeCode services.
 It consists of all RhodeCode services required with additionally
 Edge Router(Traefik with optional SSL) and Metrics Stack (Prometheus, Loki, Grafana) in single environment using Docker.
 
 Using a docker-compose this setup creates following services for RhodeCode:
 
 
 
 **Router (mandatory to run):**
 
 
 .. code-block:: bash
 
     ./rcstack router --help
 
 
 `Traefik <https://doc.traefik.io/traefik/>`_ aka Edge Router is responsible for handling all outgoing and incoming traffic to whole stack.
 It can do SSL termination, and handle SSL traffic with certificate management.
 
 Traefik listens to few defaults ports and
 handles all incoming/outgoing traffic to the stack
 
 - 80   (HTTP)
 - 443  (HTTPS)
 - 9443 (SSH for RhodeCode traffic)
 - 3100 (Loki log aggregation)
 
 
 **Services (mandatory to run):**
 
 .. code-block:: bash
 
     ./rcstack services --help
 
 
 - Database (defaults to PostgreSQL) Optionally can be replaced by MySQL, or own external database if needed.
 - Redis, acts as cache and queue exchange
 - ChannelStream - live websocket communications
 - Elasticsearch (full text search backend)
 - Nginx (static file service) proxy serving RhodeCode static files
 
 
 **RhodeCode (mandatory to run):**
 
 .. code-block:: bash
 
     ./rcstack rhodecode --help
 
 
 - RhodeCode CE/EE web app
 - VCSServer for GIT/SVN/HG support
 - SSH server for cloning over SSH
 - SVN webserver for SVN protocol support
 - Celery workers for asynchronous tasks
 - Celery beat for scheduler and automation tasks
 
 
 **Metrics (Optional)**
 
 .. code-block:: bash
 
     ./rcstack metrics --help
 
 - Loki, logs aggregation
 - Grafana, metrics Dashboard
 - Prometheus, metrics time-series
 - Statsd-exporter - statsd to Prometheus bridge
 - Node-exporter - machine stats and usage
 - Promtail - log scraping
 
 
 .. toctree::
     :maxdepth: 1
     :hidden:
     :caption: Installation
 
     install/installation.rst
     install/upgrade.rst
 
 
 .. toctree::
     :maxdepth: 1
     :hidden:
     :caption: Configuration
 
     configuration/configuration-overview.rst
     configuration/scaling-rhodecode.rst
     configuration/enable-ssl-on-traefik.rst
     configuration/data-volumes.rst
     configuration/set-license-file.rst
+    configuration/set-specific-install-version.rst
 
 
 .. toctree::
     :maxdepth: 1
     :hidden:
     :caption: Migration
 
     migration/migration-to-docker.rst
 
 
 .. toctree::
     :maxdepth: 1
     :hidden:
     :caption: Builds & Images
 
     builds/build-new-image.rst
     builds/building-images.rst
 
 .. toctree::
     :maxdepth: 1
     :hidden:
     :caption: Changelog
 
     changes.rst
  No newline at end of file

docs/source/migration/migration-to-docker.rst

@@ -1,100 +1,110 b''
 ===================
 Migration to Docker
 ===================
 
 
 Migrate old pre 4.28.0 installer based releases
 -----------------------------------------------
 
 
 1. Decide on components use
 +++++++++++++++++++++++++++
 
 By default, RhodeCode stack uses Redis and Postgres. 
 We recommend using those in Docker as things like
 backup/restore are much easier, and possible to run by our installer
 
 If you plan to use your own redis or DB, disable those services in
 :file:`.custom/docker-compose-services.override.yaml` by setting ``replicas: 0``
 
 TODO: SEE COMPONENT CONFIGURATION
 
 Select your DB type by commenting postgres or mysql db in :file:`.custom/docker-compose-services.override.yaml`
 For Sqlite, disable both DB types.
 
 .. note::
 
    Selecting your own Redis, DB etc would require pointing to those instance inside .ini config files. By default
    rcstack is configured to talk to docker based addresses of those services.
 
 
 2. Copy over your old configuration into new shared config dir
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. code-block::
 
     cp rhodecode.ini to config/_shared/rhodecode_old.ini
     cp vcsserver.ini to config/_shared/vcsserver_old.ini
 
 Then compare the new files e.g :file:`rhodecode.ini` with :file:`rhodecode_old.ini` and adjust accordingly,
 most important are location of storages/redis/db connection urls.
 
 
 3. launch stack based on get started
 ++++++++++++++++++++++++++++++++++++
 
 Run an init command & launch the full stack
 
 .. code-block::
 
     ./rcstack init
     ./rcstack stack all up -d
 
 
 4. make a db dump
 +++++++++++++++++
 
 If docker-based DB is selected, otherwise this step can be skipped.
 
 create a backup of your existing database, so it can be migrated to docker instance.
 If you plan to use you old running DB, this step can be omitted.
 Adjust rhodecode.ini to point your docker rhodecode to old DB
 
 
 5. restore db
 +++++++++++++
 
 If docker-based DB is selected
 Restore the database into docker container running DB
 
+
+6. move data into docker storage
+++++++++++++++++++++++++++++++++
+
+Step one is to move the required componenst to the :file:`.custom/storage` directory inside the docker
+compose stack. This directory is mounted later on so data can be copied over into docker storage engine volumes.
+
+
 .. code-block::
 
     #. mv repositories data to .custom/storage
     +++++
 
     #. mv gists data to .custom/storage
     +++++
 
     #. mv artifacts data to .custom/storage
     +++++
 
+
+Once that is done.
+
+.. code-block::
+
+
     #. mv tarball cache data to .custom/storage
     +++++
 
     #. ./rcstack cli storage
     +++++
 
     #. move repos to /vol/repovolume
     +++++
 
     #. move artifacts data to /vol/datavolume
     +++++
 
     #. move tarballcache data to /vol/datavolume
     +++++
 
-    #. cp rhodecode.ini to config/_shared/rhodecode.ini
-    +++++
 
-    #. cp vcsserver.ini to config/_shared/vcsserver.ini
-    +++++