README.md

# RhodeCode Cluster

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.

Using a docker-compose this setup creates following services for RhodeCode:

Edge-Router (Mandatory):

 - 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

 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