xrpl-dev-portal/content/infrastructure/clio/install-clio-on-ubuntu.md

html, parent, blurb, labels

html	parent	blurb	labels
install-clio-on-ubuntu.html	infrastructure.html	Install a precompiled Clio binary on Ubuntu Linux.	Clio Server

Install Clio on Ubuntu Linux

This page describes the recommended instructions for installing the latest stable version of Clio on Ubuntu Linux 20.04 or higher using the apt utility.

These instructions install a binary that has been compiled by Ripple. For instructions on how to build Clio from source, see the Clio source code repository.

Prerequisites

Before you install Clio, you must meet the following requirements.

• Ensure that your system meets the system requirements.

  Note: Clio has the same system requirements as the rippled server, except Clio needs less disk space to store the same amount of ledger history.

• You need compatible versions of CMake and Boost. Clio requires C++20 and Boost 1.75.0 or higher.

• Access to a Cassandra cluster that is running locally or remote. You can choose to install and configure a Cassandra cluster manually by following the Cassandra installation instructions, or run Cassandra on a Docker container using one of the following commands.

  • If you choose to persist Clio data, run Cassandra in a Docker container and specify an empty directory to store Clio data:

     docker run --rm -it --network=host --name cassandra  -v $PWD/cassandra_data:/var/lib/
     cassandra cassandra:4.0.4
    

  • If you do not wish to persist Clio data, run the following command:

      docker run --rm -it --network=host --name cassandra cassandra:4.0.4
    

• You need gRPC access to one or more rippled servers in P2P mode. The rippled servers can either be local or remote, but you must trust them. The most reliable way to do this is to install rippled yourself.

Installation Steps

1. Update repositories:

    sudo apt -y update
   

   Tip: If you have already installed an up-to-date version of rippled on the same machine, you can skip the following steps for adding Ripple's package repository and signing key, which are the same as in the rippled install process. Resume from step 5, "Fetch the Ripple repository."

2. Install utilities:

    sudo apt -y install apt-transport-https ca-certificates wget gnupg
   

3. Add Ripple's package-signing GPG key to your list of trusted keys:

    sudo mkdir /usr/local/share/keyrings/
    wget -q -O - "https://repos.ripple.com/repos/api/gpg/key/public" | gpg --dearmor > ripple-key.gpg
    sudo mv ripple-key.gpg /usr/local/share/keyrings
   

4. Check the fingerprint of the newly-added key:

    gpg /usr/local/share/keyrings/ripple-key.gpg
   

   The output should include an entry for Ripple such as the following:

    gpg: WARNING: no command supplied.  Trying to guess what you mean ...
    pub   rsa3072 2019-02-14 [SC] [expires: 2026-02-17]
        C0010EC205B35A3310DC90DE395F97FFCCAFD9A2
    uid           TechOps Team at Ripple <techops+rippled@ripple.com>
    sub   rsa3072 2019-02-14 [E] [expires: 2026-02-17]
   

   In particular, make sure that the fingerprint matches. (In the above example, the fingerprint is on the third line, starting with C001.)

5. Add the appropriate Ripple repository for your operating system version:

    echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/rippled-deb focal stable" | \
        sudo tee -a /etc/apt/sources.list.d/ripple.list
   

   The above example is appropriate for Ubuntu 20.04 Focal Fossa.

6. Fetch the Ripple repository.

    sudo apt -y update
   

7. Install the Clio software package. There are two options:

   • To run rippled on the same machine, install the clio package, which sets up both servers:

       sudo apt -y install clio
     

   • To run Clio on a separate machine from rippled, install the clio-server package, which sets up Clio only:

       sudo apt -y install clio-server
     

8. If you are running rippled on a separate machine, modify your Clio config file to point to it. You can skip this step if you used the clio package to install both on the same machine.

   1. Edit the Clio server's config file to modify the connection information for the rippled server. The package installs this file at /opt/clio/etc/config.json.

       "etl_sources":
       [
           {
               "ip":"127.0.0.1",
               "ws_port":"6006",
               "grpc_port":"50051"
           }
       ]
      

      This includes:

      • The IP of rippled server.
      • The port where rippled accepts unencrypted WebSocket connections.
      • The port where rippled accepts gRPC requests.

      Note You can use multiple rippled servers as a data source by add more entries to the etl_sources section. If you do, Clio load balances requests across all the servers in the list, and can keep up with the network as long as at least one of the rippled servers is synced.

      The example config file accesses the rippled server running on the local loopback network (127.0.0.1), with the WebSocket (WS) on port 6006 and gRPC on port 50051.

   2. Update the rippled server's config file to allow the Clio server to connect to it. The package installs this file at /etc/opt/ripple/rippled.cfg.

      • Open a port to accept unencrypted WebSocket connections.

          [port_ws_public]
          port = 6005
          ip = 0.0.0.0
          protocol = ws
        

      • Open a port to handle gRPC requests and specify the IP(s) of Clio server(s) in the secure_gateway entry.

          [port_grpc]
          port = 50051
          ip = 0.0.0.0
          secure_gateway = 127.0.0.1
        

        Tip: If you are not running Clio on the same machine as rippled, change the secure_gateway in the example stanza to use the IP address of the Clio server.

9. Enable and start the Clio systemd service.

    sudo systemctl enable clio
   

10. Start the rippled and Clio servers.

     sudo systemctl start rippled
     sudo systemctl start clio
    

    If you are starting with a fresh database, Clio needs to download the full ledger. This can take some time. If you are starting both servers for the first time, it can take even longer because Clio waits for rippled to sync before extracting ledgers.

See Also

• Concepts:
  • The Clio Server