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:

   • Install psql

   sudo apt-get install postgresql-client
   • Query Postgress-db-sync sync progress:

   psql -d cexplorer -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;"

   Optionally query remotely with ssh, but replace user@x.x.x.x with actual credentials:

   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;\""

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.

Operation	Dependency
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.