Skip to main content

Step 2. Setup Partner-chain dependencies

Now that a Cardano SPO is set up, it is time to configure partner-chain dependencies such as Ogmios, Kupo, DB-sync, Postgres, and Cardano-node. To simplify the process, a Docker Compose file is provided to easily start these services on a server. Alternatively, one may choose to build these dependencies from source.

Minimum system requirements​

See Partner-chain dependencies server requirements.

2a. docker-compose up partner-chain dependencies​

  1. Clone partner-chain dependencies repo and navigate to compose.yml file:

    git clone git@github.com:midnight-ntwrk/partner-chain-deps-docker.git
    cd partner-chain-deps-docker

  2. Edit compose.yml file:

    • Edit the compose.yml file using VSCode or a shell editor such as vim. For example, with vim:
    vim compose.yml
    • Enter I key to enter insert mode.
    • Navidate using arrow keys and locate POSTGRESS environment variables.
    - POSTGRES_HOST=postgres
    - POSTGRES_PORT=5432
    - POSTGRES_DB=cexplorer
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=password123
    • ⚠️ Change the default values for POSTGRES_PASSWORD and POSTGRES_USER to a more secure username and password.
    • If using vim editor, make changes, then ESC + :wq to save changes to file.

  3. docker-compose up partner-chain dependencies:

    • Within the same directory as the compose.yml, launch partner-chain dependencies in detatched mode.
    docker-compose up -d

    Example output:

    [+] Running 5/5
    ✔ Container postgres      H...                                 5.7s 
    ✔ Container cardano-node  Started                              0.1s 
    ✔ Container ogmios        Sta...                               0.2s 
    ✔ Container kupo          Start...                             0.2s 
    ✔ Container db-sync       St...                                5.8s
    important

    Allow partner-chain dependencies to sync 100% with the Cardano network. See the next step for monitoring these services.

2b. Managing and monitoring partner-chain dependencies​

  1. Verify status of services and ports:

    • List active Docker containers along with their status, ports, and container IDs:
    docker container list

    Example output:

    CONTAINER ID   IMAGE                                           COMMAND                  CREATED       STATUS                 PORTS                    NAMES
    1fc7a31bfbdd   ghcr.io/intersectmbo/cardano-db-sync:13.3.0.0   "/nix/store/zixwwxp8…"   5 hours ago   Up 28 seconds                                   db-sync
    761b9b4c2660   cardanosolutions/kupo:v2.9.0                    "/bin/kupo --node-so…"   5 hours ago   Up 5 hours (healthy)   0.0.0.0:1442->1442/tcp   kupo
    4635106f0f09   cardanosolutions/ogmios:v6.5.0                  "/bin/ogmios --host …"   5 hours ago   Up 5 hours (healthy)   0.0.0.0:1337->1337/tcp   ogmios
    010d79d05a81   postgres:15.3                                   "docker-entrypoint.s…"   5 hours ago   Up 5 hours (healthy)   0.0.0.0:5432->5432/tcp   postgres
    acbb584f9dfd   ghcr.io/intersectmbo/cardano-node:9.1.0         "entrypoint"             5 hours ago   Up 26 seconds                                   cardano-node

  2. View logs of specific containers:

    To view logs of a particular container, use docker logs followed by the container name or ID:

    docker logs db-sync
    docker logs ogmios
    docker logs kupo
    docker logs postgres
    docker logs cardano-node

    Replace db-sync, ogmios, etc., with the actual container names or IDs you want to inspect.

  3. View Ogmios and Kupo dashboards:

    If one's server IP is x.x.x.x and they wish to access a service running on port 1337, such as Ogmios, they would enter the following into their browser's address bar:

    http://x.x.x.x:1337

  4. Query Cardano-db-sync synchronization progress:

    • Using psql directly:

      If you don’t already have the PostgreSQL client installed, you can install it using:

      sudo apt-get install postgresql-client

      Log in to PostgreSQL shell using psql:

       psql -h localhost -U postgres -d cexplorer -p 5432

      Optionally, log in to PostgreSQL shell using docker:

      docker exec -it db-sync-postgres psql -U postgres -d cexplorer

      Then, run the following query inside the PostgreSQL shell:

      SELECT 100 * (
          EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) -
          EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
      ) / (
          EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) -
          EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
      ) AS sync_percent
      FROM block;

    • Using ssh remotely:

      If you want to query remotely, run this command via SSH:

      ssh user@x.x.x.x -C "psql -d cexplorer -h localhost -p 5432 -U postgres -c \"SELECT 100 * (EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) - EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) / (EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) - EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) AS sync_percent FROM block;\""

      Replace user@x.x.x.x with your SSH username and server IP address.

  5. Useful docker-compose commands:

    To learn more about Docker Compose, visit the official Docker Compose documentation. However, here are some common commands:

    docker-compose stop # stop containers
    docker-compose start # start containers
    docker-compose restart # restart containers
    docker-compose down # stop and remove containers
    docker-compose stats # display resource usage statistics

2c. Firewall rule considerations​

Partner-chain-dependency services are important for 2 main operations.

OperationDependency
Validator registration/ deregistration: This is the process of using the partner-chains-cli to generate partner-chain keys and register as a candidate in the Midnight validator committee.Needs Ogmios: x.x.x.x:1337 and Kupo: x.x.x.x:1442 service ports.
Run Midnight node in validator mode: A Midnight validator node needs to follow the partner-chain governance and commitee scripts on the Cardano chain. It does this via Postgres-db-sync.Needs Postgres-db-sync: x.x.x.x:5432 services port.

Therefore, the machine intended to perform the registation needs access to Kupo and Ogmios and the machine intended to run the Midnight-node needs access to Postgres-db-sync.

tip

It's easier to perform the registration on the same machine as partner-chain dependencies.

Here's how you can configure ufw (Uncomplicated Firewall) to allow traffic for Ogmios, Kupo, and Postgres-db-sync:

1. Ensure ufw is Installed

  • First, make sure ufw is installed on the partner-chain depedencies server. If not, you can install it:

    sudo apt update
    sudo apt install ufw

2. Set Default Policies

  • Set the default policies to deny incoming traffic:

    sudo ufw default deny incoming
    sudo ufw default allow outgoing

3. Allow Specific Services

  • Now, allow the specific ports needed:

    # Allow Ogmios
    sudo ufw allow 1337/tcp

    # Allow Kupo
    sudo ufw allow 1442/tcp

    # Allow Postgres-db-sync
    sudo ufw allow 5432/tcp

4. Enable ufw

  • Enable the firewall. This command will start ufw and also set it to start on boot:
sudo ufw enable

5. Check the Status

To ensure the rules have been added correctly:

sudo ufw status

This should list out the rules you've just added, showing that traffic on ports 1337, 1442, and 5432 for TCP is allowed.

6. Allow from Specific IP

  • If you want to restrict these services to only be accessible from a specific IP or range:
# Replace x.x.x.x with the IP address or range.
sudo ufw allow from x.x.x.x to any port 1337 proto tcp
sudo ufw allow from x.x.x.x to any port 1442 proto tcp
sudo ufw allow from x.x.x.x to any port 5432 proto tcp

Notes:​

  • SSH: If you're configuring this remotely, ensure you don't lock yourself out. Allow SSH (port 22 by default) before enabling ufw:

    sudo ufw allow ssh

  • Reboot: Sometimes, a system reboot can ensure all settings are properly applied, although ufw typically applies changes immediately.

  • Logging: You might want to enable logging for troubleshooting or monitoring:

    sudo ufw logging on

This setup ensures that only the necessary ports for Ogmios, Kupo, and Postgres-db-sync are open, enhancing the security of your workstation or server while allowing the required services to function for the Midnight validator registration process.