From 3963c07d1468faa2ca1be036a9a56e6f948ee410 Mon Sep 17 00:00:00 2001 From: ionutboangiu Date: Thu, 22 Jun 2023 11:32:45 -0400 Subject: [PATCH] Update installation docs --- docs/installation.rst | 297 +++++++++++++++++++----------------------- 1 file changed, 132 insertions(+), 165 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index a07081bd6..af7ff93b0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -3,268 +3,235 @@ .. _PostgreSQL: https://www.postgresql.org/ .. _MongoDB: https://www.mongodb.com/ - - - .. _installation: Installation ============ -CGRateS can be installed via packages as well as Go automated source install. -We recommend using source installs for advanced users familiar with Go programming and packages for users not willing to be involved in the code building process. +.. contents:: + :local: + :depth: 2 +CGRateS can be installed either via packages or through an automated Go source installation. We recommend the latter for advanced users familiar with Go programming, and package installations for those not wanting to engage in the code building process. -Using packages --------------- +After completing the installation, you need to perform the :ref:`post-install configuration ` steps to set up CGRateS properly and prepare it to run. After these steps, CGRateS will be configured in **/etc/cgrates/cgrates.json** and the service can be managed using the **systemctl** command. -Depending on the packaged distribution, the following methods are available: +Package Installation +-------------------- +Package installation method varies according to the Linux distribution: -Debian -^^^^^^ +Debian or Debian-based Distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There are two main ways of installing the maintained packages: +You can add the CGRateS repository to your system's sources list as follows: +.. code-block:: bash -Aptitude repository -~~~~~~~~~~~~~~~~~~~ + # Install dependencies + sudo apt-get install wget gnupg -y + # Download and move the GPG Key to the trusted area + wget https://apt.cgrates.org/apt.cgrates.org.gpg.key -O apt.cgrates.org.asc + sudo mv apt.cgrates.org.asc /etc/apt/trusted.gpg.d/ -Add the gpg key: + # Add the repository to the apt sources list + echo "deb http://apt.cgrates.org/debian/ v0.10 main" | sudo tee /etc/apt/sources.list.d/cgrates.list -:: + # Update the system repository and install CGRateS + sudo apt-get update -y + sudo apt-get install cgrates -y - sudo wget https://apt.cgrates.org/apt.cgrates.org.gpg.key -O /etc/apt/trusted.gpg.d/apt.cgrates.org.asc +Alternatively, you can manually install a specific .deb package as follows: -Add the repository in apt sources list: +.. code-block:: bash -:: + wget http://pkg.cgrates.org/deb/v0.10/cgrates_current_amd64.deb + sudo dpkg -i ./cgrates_current_amd64.deb - echo "deb http://apt.cgrates.org/debian/ nightly main" | sudo tee /etc/apt/sources.list.d/cgrates.list +.. note:: + A complete archive of CGRateS packages is available at http://pkg.cgrates.org/deb/. -Update & install: +Redhat-based Distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +For .rpm distros, we are using copr to manage the CGRateS packages: - sudo apt-get update - sudo apt-get install cgrates +- If using a version of Linux with dnf: + .. code-block:: bash -Once the installation is completed, one should perform the :ref:`post_install` section in order to have the CGRateS properly set and ready to run. -After *post-install* actions are performed, CGRateS will be configured in **/etc/cgrates/cgrates.json** and enabled in **/etc/default/cgrates**. + # sudo yum install -y dnf-plugins-core on RHEL 8 or CentOS Stream + sudo dnf install -y dnf-plugins-core + sudo dnf copr -y enable cgrates/v0.10 + sudo dnf install -y cgrates +- For older distributions: -Manual installation of .deb package out of archive server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: bash + sudo yum install -y yum-plugin-copr + sudo yum copr -y enable cgrates/v0.10 + sudo yum install -y cgrates -Run the following commands: +To install a specific version of the package, run: -:: +.. code-block:: bash - wget http://pkg.cgrates.org/deb/nightly/cgrates_current_amd64.deb - dpkg -i cgrates_current_amd64.deb + sudo dnf install -y cgrates-.x86_64 -As a side note on http://pkg.cgrates.org/deb/ one can find an entire archive of CGRateS packages. +.. note:: + The entire archive of CGRateS rpm packages is available at https://copr.fedorainfracloud.org/coprs/cgrates/v0.10/packages/. +Installing from Source +---------------------- -Redhat/Fedora/CentOS -^^^^^^^^^^^^^^^^^^^^ +Prerequisites: +^^^^^^^^^^^^^^ -There are two main ways of installing the maintained packages: +- **Git** +.. code-block:: bash -YUM repository -~~~~~~~~~~~~~~ + sudo apt-get install -y git + # sudo dnf install -y git for .rpm distros +- **Go** (refer to the official Go installation docs: https://go.dev/doc/install) -To install CGRateS out of YUM execute the following commands +To install the latest Go version at the time of writing this documentation, run: -:: - - sudo tee -a /etc/yum.repos.d/cgrates.repo > /dev/null <` - * Git + sudo dnf install -y rpm-build wget curl tar - :: + # Create build directories + mkdir -p $HOME/cgr_build/{BUILD,RPMS,SOURCES,SPECS,SRPMS} - sudo apt-get install git + # Fetch source code + cd $HOME/go/src/github.com/cgrates/cgrates + export gitLastCommit=$(git rev-parse HEAD) + export rpmTag=$(git log -1 --format=%ci | date +%Y%m%d%H%M%S)+$(git rev-parse --short HEAD) + wget -P $HOME/cgr_build/SOURCES https://github.com/cgrates/cgrates/archive/$gitLastCommit.tar.gz + # Copy RPM spec file + cp $HOME/go/src/github.com/cgrates/cgrates/packages/redhat_fedora/cgrates.spec $HOME/cgr_build/SPECS - * RPM - - :: - - sudo apt-get install rpm - -Execute the following commands - -:: - - cd $HOME/go/src/github.com/cgrates/cgrates - export gitLastCommit=$(git rev-parse HEAD) - export rpmTag=$(git log -1 --format=%ci | date +%Y%m%d%H%M%S)+$(git rev-parse --short HEAD) - mkdir -p $HOME/cgr_build/{BUILD,RPMS,SOURCES,SPECS,SRPMS} - wget -P $HOME/cgr_build/SOURCES https://github.com/cgrates/cgrates/archive/$gitLastCommit.tar.gz - cp $HOME/go/src/github.com/cgrates/cgrates/packages/redhat_fedora/cgrates.spec $HOME/cgr_build/SPECS - cd $HOME/cgr_build - rpmbuild -bb --define "_topdir $HOME/cgr_build" SPECS/cgrates.spec - + # Build RPM package + cd $HOME/cgr_build + rpmbuild -bb --define "_topdir $HOME/cgr_build" SPECS/cgrates.spec .. _post_install: -Post-install ------------- +Post-install Configuration +-------------------------- - -Database setup +Database Setup ^^^^^^^^^^^^^^ -For its operation CGRateS uses **one or more** database types, depending on its nature, install and configuration being further necessary. +CGRateS supports multiple database types for various operations, based on your installation and configuration. -At present we support the following databases: +Currently, we support the following databases: `Redis`_ - Can be used as :ref:`DataDB`. - Optimized for real-time information access. - Once installed there should be no special requirements in terms of setup since no schema is necessary. + This can be used as :ref:`DataDB`. It is optimized for real-time information access. Post-installation, no additional setup is required as Redis doesn't require a specific schema. `MySQL`_ - Can be used as :ref:`StorDB`. - Optimized for CDR archiving and offline Tariff Plan versioning. - Once MySQL is installed, CGRateS database needs to be set-up out of provided scripts. (example for the paths set-up by debian package) + This can be used as :ref:`StorDB` and is optimized for CDR archiving and offline Tariff Plan versioning. Post-installation, you need to set up the CGRateS database using the provided scripts: - :: +.. code-block:: bash - cd /usr/share/cgrates/storage/mysql/ - ./setup_cgr_db.sh root CGRateS.org localhost + cd /usr/share/cgrates/storage/mysql/ + sudo ./setup_cgr_db.sh root CGRateS.org localhost `PostgreSQL`_ - Can be used as :ref:`StorDB`. - Optimized for CDR archiving and offline Tariff Plan versioning. - Once PostgreSQL is installed, CGRateS database needs to be set-up out of provided scripts (example for the paths set-up by debian package). + Like MySQL, PostgreSQL can be used as :ref:`StorDB`. Post-installation, you need to set up the CGRateS database using the provided scripts: - :: +.. code-block:: bash - cd /usr/share/cgrates/storage/postgres/ - ./setup_cgr_db.sh + cd /usr/share/cgrates/storage/postgres/ + ./setup_cgr_db.sh `MongoDB`_ - Can be used as :ref:`DataDB` as well as :ref:`StorDB`. - It is the first database that can be used to store all kinds of data stored from CGRateS from accounts, tariff plans to cdrs and logs. - Once MongoDB is installed, CGRateS database needs to be set-up out of provided scripts (example for the paths set-up by debian package) + MongoDB can be used as both :ref:`DataDB` and :ref:`StorDB`. This is the first database that can store all types of data from CGRateS - from accounts, tariff plans to CDRs and logs. Post-installation, you need to set up the CGRateS database using the provided scripts: - :: +.. code-block:: bash - cd /usr/share/cgrates/storage/mongo/ - ./setup_cgr_db.sh + cd /usr/share/cgrates/storage/mongo/ + ./setup_cgr_db.sh - -Set versions data +Set Versions Data ^^^^^^^^^^^^^^^^^ -Once database setup is completed, we need to write the versions data. To do this, run migrator tool with the parameters specific to your database. +After completing the database setup, you need to write the versions data. To do this, run the migrator tool with the parameters specific to your database. Sample usage for MySQL: -:: - cgr-migrator -stordb_passwd="CGRateS.org" -exec="*set_versions" +.. code-block:: bash + cgr-migrator -stordb_passwd="CGRateS.org" -exec="*set_versions" \ No newline at end of file