Table Of Contents

• MeritRank
  • Batch loading (cold start)
  • Stats collection (optional)
• How to Launch the Project with Docker
  • Docker Installation
  • One-Command Installation with Docker
  • Building the Project
    • Building the service
    • Building the psql-connector
  • Creating a Network
  • Launching the Containers
    • Running mr-service
    • Running mr-psql-connector
  • Using psql
• Manual Launch Instructions
  • Quick Installation with One Command
    • Launching the service
    • Initializing and Running psql-connector with pgrx
  • Required Dependencies
    • PostgreSQL Build Dependencies
    • Rust Toolchain Dependencies
    • Clang (v7 or Newer) and Git
  • Launching the service
  • Launching psql-connector
  • Using pgrx
    • Installing the cargo-pgrx Sub-command
    • Initializing PGRX in Your Project
  • Testing and Starting the Service
  • Connecting to the Database

MeritRank

• Core
• Service
• PSQL Connector

Batch loading (cold start)

After a service restart, loading many edges one-by-one with mr_put_edge can be slow. Use batch loading to send all edges in a single request:

• SQL: mr_bulk_load_edges(src_arr, dst_arr, weight_arr, magnitude_arr, context_arr, timeout_msec) — see PSQL Connector.
• The service clears existing walks, loads the edges without computing walks, and blocks other requests until the load finishes. Walks are created lazily on first score/graph/neighbor reads per ego.

Stats collection (optional)

Ops queue and processing-time stats are off by default. To enable them (e.g. for load testing or tuning), set MERITRANK_COLLECT_STATS=true. Then use ResetStats and GetStats via the protocol; see Service env vars.

How to Launch the Project with Docker

Docker Installation

To install Docker on a Debian-based system, follow the steps provided on Docker's official site.

One-Command Installation with Docker

If you'd like a shortcut that prepares everything in a single command, use the following:

sudo apt install docker.io git && \
git clone https://github.com/Intersubjective/meritrank-rust.git && \
cd meritrank-rust && \
docker build -t mr-service -f service/Dockerfile . && \
docker build -t mr-psql-connector -f psql-connector/Dockerfile . && \
docker network create my-network && \
docker run --network my-network -p 10234:10234 -e MERITRANK_SERVICE_URL=tcp://0.0.0.0:10234 --detach --name container1 mr-service && \
docker run --network my-network -e POSTGRES_PASSWORD=postgres -e MERITRANK_SERVICE_URL=tcp://container1:10234 --detach --name container2 -p 5432:5432 mr-psql-connector:latest

Building the Project

Ensure you have git and docker installed before running these commands. We’ll build both the service and the psql-connector.

Building the service

git clone https://github.com/Intersubjective/meritrank-rust.git
cd meritrank-rust
docker build -t mr-service -f service/Dockerfile .

Building the psql-connector

docker build -t mr-psql-connector -f psql-connector/Dockerfile .

Creating a Network

Creating a shared network is necessary for smooth communication between mr-service and mr-psql-connector. By setting up a custom network (my-network), the containers can communicate directly by container name, simplifying the connection setup specified in MERITRANK_SERVICE_URL.

docker network create my-network

Launching the Containers

Running mr-service

Use this command to launch mr-service:

docker run --network my-network -p 10234:10234 -e MERITRANK_SERVICE_URL=tcp://0.0.0.0:10234 --name container1 mr-service

• --network my-network: Connects mr-service to the shared network.
• -p 10234:10234: Exposes the service on port 10234 for external access.
• The tcp://0.0.0.0 address configures the service to listen on all network interfaces, enabling connections to port 10234 from any reachable IP.

Running mr-psql-connector

Then, run this command to start mr-psql-connector:

docker run --network my-network -e POSTGRES_PASSWORD=postgres -e MERITRANK_SERVICE_URL=tcp://container1:10234 --name container2 -p 5432:5432 mr-psql-connector:latest

• --network my-network: Connects mr-psql-connector to the shared network.
• -e POSTGRES_PASSWORD=postgres: Sets a password for the default PostgreSQL user (required to avoid errors).
• The MERITRANK_SERVICE_URL=tcp://container1:10234 connection string links to mr-service at port 10234.
• --name container2: Names the container container2.
• -p 5432:5432: Exposes PostgreSQL on port 5432 for external access.

Using psql

You can open an interactive shell session inside container2 as the PostgreSQL user to manage your database.

docker exec -it container2 su - postgres && psql

Here are some basic commands to try:

\df
SELECT mr_service_url(); 
SELECT mr_service(); 
SELECT mr_create_context('my-context'); 

Manual Launch Instructions

Quick Installation with One Command

If you’d prefer to install everything with a single command that also verifies Rust’s installation on your system, use the following:

sudo apt-get install build-essential libreadline-dev zlib1g-dev flex bison libxml2-dev libxslt-dev libssl-dev libxml2-utils xsltproc ccache pkg-config rustc clang git cmake && \
if command -v rustc &> /dev/null; then echo "Rust is already installed"; else curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && source "$HOME/.cargo/env"; fi && \
git clone https://github.com/Intersubjective/meritrank-rust.git

Launching the service

To start the service, from the repo root run:

cd meritrank-rust && cargo run -p meritrank_service > log.txt 2>&1

Or from the service directory: cd meritrank-rust/service && cargo run > log.txt 2>&1

Initializing and Running psql-connector with pgrx

Proceed to the psql-connector directory, initialize, and start pgrx:

cd ../psql-connector
cargo install --locked cargo-pgrx
cargo pgrx init
cargo pgrx run

Required Dependencies

Before launching the project, ensure all necessary dependencies are installed. For Debian-based distributions, use the following commands:

PostgreSQL Build Dependencies

sudo apt-get install build-essential libreadline-dev zlib1g-dev flex bison libxml2-dev libxslt-dev libssl-dev libxml2-utils xsltproc ccache pkg-config

Rust Toolchain Dependencies

sudo apt-get install rustc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Install rustup
source "$HOME/.cargo/env" # Add Rust to PATH

Clang (v7 or Newer) and Git

sudo apt-get install clang git

Launching the service

To start meritrank-service-rust, from the repo root use:

cd meritrank-rust
cargo run -p meritrank_service

Launching psql-connector

Navigate to the psql-connector directory:

cd meritrank-rust/psql-connector

Using pgrx

Some steps for setting up pgrx are covered on the pgrx GitHub page.

Installing the cargo-pgrx Sub-command

cargo install --locked cargo-pgrx 

Initializing PGRX in Your Project

This command will download, compile supported PostgreSQL versions into ${PGRX_HOME}, and run initdb:

cargo pgrx init

Testing and Starting the Service

To run automated tests:

export RUST_TEST_THREADS=1 
cargo pgrx test

If tests pass without errors, you can launch the service with:

cargo pgrx run

Connecting to the Database

To access psql and interact with MeritRank’s service via the psql connector, log in as the postgres user and open psql:

su - postgres
psql

You can now execute the following commands to verify that the service is running correctly:

\df
SELECT mr_service_url();
SELECT mr_service();
SELECT mr_create_context('my-context');